Fluxo de Release com Changesets
A Fábrica de Cálculos usa Changesets para versionar pacotes e gerar CHANGELOG.md de forma automatizada. Alterações de código em apps ou packages com efeito em consumidores passam por esse fluxo — sem changeset, o pipeline não detecta o que buildar e deployar.
Visão geral
flowchart TD
A[branch de trabalho] -->|MR para develop<br/>na interface do GitLab| B[develop]
B -->|bot abre MR| C["MR 'Version Packages'<br/>(bumps + CHANGELOG)"]
C -->|merge em develop| D[CI builda<br/>deploy dev automático]
D -->|clique manual no GitLab| E[deploy stg]
E -->|merge develop → main| F[CI prepara produção]
F -->|deploy e publicação manuais<br/>pelo admin| G[comunicado de release<br/>visível ao usuário]
O ciclo passa por desenvolvimento, homologação e produção. A promoção é feita pelo pipeline e pelas revisões previstas no fluxo do projeto. Configurações, endereços, restrições de rede e procedimentos operacionais ficam na documentação interna.
O repositório e o ciclo de um trabalho
O repositório vive em três remotos com papéis distintos:
| Remoto | Papel |
|---|---|
origin | Hub de colaboração, no GitHub. É o upstream dos develop e main locais. |
gitlab | Hub de publicação, no GitLab da Justiça Federal da 3ª Região. Concentra o CI/CD, os deploys e o rastreador de issues. |
gitjus | Espelho no GitLab do CNJ. Recebe atualizações apenas por espelhamento. |
No hub de publicação, develop reflete o que está em desenvolvimento e homologação e main reflete a produção. Nenhum dos dois recebe push direto: eles só avançam por merge request (MR) aceito na interface do GitLab, que é o gatilho do pipeline.
- Crie o branch a partir do
developlocal, já sincronizado com o hub de publicação. - Faça o trabalho e crie o changeset (passo a passo abaixo).
- Publique o branch no hub de publicação com
git push -u gitlab <branch>. O pipeline do MR roda os testes dos pacotes alterados e o bot comenta se faltar changeset. - Abra o MR para
developpela interface do GitLab. O merge acontece em duas etapas: primeiro o MR do branch, depois o MR "Version Packages" que o bot gera com os bumps de versão e osCHANGELOG.md. - Concluído o deploy em desenvolvimento e homologação, traga o resultado para a máquina local (
git pull gitlab develop) e devolva ao hub de colaboração (git push origin develop). - A promoção para produção é o MR de
developparamain, também pela interface do GitLab; depois do merge, repita a sincronização paramain.
Em caráter excepcional, diante de bug grave em produção, o branch de correção deriva direto de main — veja Hotfix urgente em produção. Fora dessa hipótese, todo trabalho nasce de develop.
Colaboradores sem acesso ao hub de publicação contribuem por pull request no GitHub, contra develop, com o changeset incluído. A revisão acontece no pull request; aprovado, um mantenedor publica o mesmo branch no hub de publicação, sem reescrever os commits, e abre o MR lá. O merge por merge commit faz o pull request aparecer como mesclado assim que develop é sincronizado de volta ao GitHub.
Passo a passo: adicionar um changeset
1. Faça suas alterações normalmente
Edite o código de apps ou packages em uma branch dedicada. Mudanças apenas em documentação, scripts, hooks ou CI não exigem changeset.
2. Rode o CLI na raiz do monorepo
bash
pnpm changeset3. Selecione os pacotes alterados
Use espaço para marcar e enter para confirmar.
4. Escolha o tipo de bump
Para cada pacote, o CLI pergunta o tipo de mudança. Veja a tabela abaixo.
5. Descreva a mudança
Escreva uma frase clara em português. Esse texto:
- Vai parar no
CHANGELOG.mddo pacote. - Em produção, vira o corpo do comunicado apresentado ao usuário final.
Evite jargão técnico interno. Em vez de "corrige notasSelicEc113AtualizacaoBase", prefira "Corrige a aplicação da Selic na atualização da base de cálculo após a EC 113".
6. Commit do arquivo gerado
O CLI cria um arquivo em .changeset/<nome-aleatorio>.md. Adicione-o ao seu commit, junto com as alterações de código.
bash
git add .changeset/
git commit -m "feat(prev-tc): adiciona suporte a benefício de transição"7. Publique o branch e abra o MR para develop
bash
git push -u gitlab <branch>Abra o MR pela interface do GitLab. Daqui em diante, o bot e o CI tomam conta: o pipeline do MR testa os pacotes alterados e, após o merge, o job release do develop consolida os changesets pendentes no MR "Version Packages".
Qual bump escolher?
| Bump | Quando usar | Exemplo |
|---|---|---|
patch | Bugfix, ajuste de comportamento sem nova feature, melhora interna, bump por dependência. | Corrigir cálculo de carência pós-EC 103 |
minor | Nova funcionalidade compatível, novo endpoint, novo cálculo, novo componente público. | Nova tela de benefício de transição em prev-tc |
major | Breaking change — remove API pública, muda assinatura, muda resultado de cálculo já em uso em prod. | Recálculo de RMI para LC 123 que altera valores anteriores |
Cuidado especial em @fc/calculos-*
Qualquer alteração que mude o resultado de um cálculo já produzido em prod é major. Usuários têm cálculos salvos na nuvem que podem ser reabertos e dar resultado diferente — eles precisam ser avisados via comunicado de release.
Dependências internas
Pacotes do monorepo se referenciam via workspace:*. Quando um pacote como @fc/calculos-previdenciarios muda, todas as apps que o consomem recebem bump automático de patch.
Não liste as apps consumidoras no changeset — apenas o pacote alterado. O Changesets descobre o resto sozinho.
Verificação antes do MR
bash
pnpm changeset statusMostra o que será versionado quando o changeset for processado. Se aparecer algo inesperado, abra o arquivo .md em .changeset/ e ajuste.
Não rode pnpm changeset version localmente
Esse comando é executado pelo bot no CI quando o MR é mergeado em develop. Rodar localmente bagunça o fluxo.
Casos comuns
Alterei só um pacote interno
Crio changeset apenas para o pacote. Apps que dependem dele recebem patch automático.
Esqueci o changeset
Sem stress. O bot avisa no MR. Adicione em commit novo no mesmo MR:
bash
pnpm changeset
git add .changeset/
git commit -m "chore: adiciona changeset"
git pushVários pacotes na mesma feature
Um único arquivo de changeset listando todos os pacotes com seus bumps respectivos. O CLI permite marcar múltiplos numa só execução.
Hotfix urgente em produção
O bot do Changesets só roda em develop. Para um hotfix direto em main, é preciso rodar manualmente o que o bot faria:
- Branch a partir de
maine aplique a correção. - Crie o changeset:
pnpm changeset. - Rode
pnpm changeset versionlocalmente — isso consome o.changeset/*.md, atualiza oCHANGELOG.mde bumpa opackage.jsondos pacotes afetados. - Comite a correção, o
CHANGELOG.mdatualizado e os bumps em um único MR direto paramain. - Mergeie → o pipeline em
maindetecta as mudanças emCHANGELOG.mde cria os jobs manuaisdeploy-prd/*. Clique para deployar. - Sincronize a correção de
mainde volta paradeveloppor uma proposta de merge revisada no GitLab. Os branches protegidos não recebem push direto.
Quando NÃO criar um changeset
Estas mudanças não entram no fluxo:
- Documentação em qualquer lugar —
apps/docs-tec/site/, READMEs públicos ou internos, comentários em código. - Documentação interna específica para agentes de IA —
CONTEXT.md,CONTEXT-MAP.md,.context/adr/,.agents/skills/e similares, contanto que não tenham repercussão emapps/docs-tec/site/. - Scripts de desenvolvimento — em
scripts/da raiz ou dentro deapps/*,packages/*,services/*. - Pacotes em
services/*— não fazem parte do release de produto. - Configuração de lint, typecheck, CI e hooks — arquivos de automação e configuração do repositório.
- Renomes ou refactors internos sem efeito visível em consumidores.
- Alterações em testes que não tocam código de produção.
Promovendo de dev para stg
Depois que o MR "Version Packages" é mergeado em develop, o pipeline detecta os CHANGELOG.md alterados, builda as apps correspondentes e deploya o dev automaticamente — você não precisa fazer nada. Mas stg exige um clique manual no GitLab.
Quem é responsável
A pessoa que mergeia o MR "Version Packages" assume duas tarefas pós-merge:
- Validar
dev— uma conferência do que mudou antes da homologação. - Promover para
stg— abrir o pipeline correspondente no GitLab e clicar em "Run" no jobdeploy-stg/*de cada app a promover.
Se não puder fazer agora, atribua explicitamente a tarefa a outra pessoa antes de seguir.
Encontrei um bug em dev
Não promova para stg. Em vez disso:
- Crie um MR com a correção, incluindo novo changeset.
- Mergeie → bot atualiza o MR "Version Packages".
- Mergeie o "Version Packages" atualizado →
devé redeployado automaticamente com a correção. - Valide novamente em
dev. - Só então promova para
stg.
Pipelines pendentes empilhados
Se mais de um MR "Version Packages" foi mergeado antes de você promover stg, vai haver múltiplos pipelines com deploy-stg/* pendentes. Sempre clique no pipeline mais recente — ele reflete o estado atual de dev. Os anteriores devem ser deixados expirar; promover um pipeline antigo iria deployar uma versão defasada para usuários piloto.
Promovendo de stg para prd
Quando stg estiver validado pelos usuários piloto, mergeie develop em main. O pipeline em main deploya prd (também manual, via clique em deploy-prd/*). Depois do deploy bem-sucedido, publique manualmente um comunicado de release no painel administrativo do backoffice, agregando o changelog das apps user-facing alteradas. (Automação desse passo é um próximo desejável, ainda não implementado.)
Conventional Commits
As mensagens de commit seguem o padrão Conventional Commits — veja Convenções de código. O título do commit não substitui o texto do changeset; são propósitos diferentes:
- Commit: rastreabilidade técnica para devs (lê no git log).
- Changeset: nota de mudança para usuário final (lê no comunicado de release).
Como saber se está funcionando?
Após mergear seu MR em develop, em alguns minutos um MR chamado "Version Packages" aparece (ou é atualizado, se já existir um aberto). Esse MR lista todos os pacotes que serão bumpados, com os textos dos changesets virando CHANGELOG.md.
Se o MR não aparece após ~5 minutos:
- Verifique se você commitou o arquivo
.mdem.changeset/. - Confira no pipeline GitLab se o job
releaserodou com sucesso.
FAQ
Posso editar CHANGELOG.md manualmente? Não. É gerado pelo Changesets. Edições manuais são sobrescritas no próximo release.
Posso bumpar package.json manualmente? Não. Isso fura o fluxo e impede o CI de detectar a mudança.
E se eu mudar a configuração do pipeline? Não precisa de changeset — alterações exclusivas na automação de CI não vão para o usuário final.
E se eu adicionar um teste novo? Se o teste cobre código que mudou (e o código tem changeset), basta. Se é só infra de testes (test-utils, fixture), tipicamente não precisa.
O bot abriu um MR "Version Packages" velho com mudanças que já estão em prod. O que faço? Provavelmente o develop divergiu do main. Sincronize develop com main primeiro; o bot vai recriar o MR atualizado.