Skip to content

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:

RemotoPapel
originHub de colaboração, no GitHub. É o upstream dos develop e main locais.
gitlabHub de publicação, no GitLab da Justiça Federal da 3ª Região. Concentra o CI/CD, os deploys e o rastreador de issues.
gitjusEspelho 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.

  1. Crie o branch a partir do develop local, já sincronizado com o hub de publicação.
  2. Faça o trabalho e crie o changeset (passo a passo abaixo).
  3. 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.
  4. Abra o MR para develop pela 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 os CHANGELOG.md.
  5. 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).
  6. A promoção para produção é o MR de develop para main, também pela interface do GitLab; depois do merge, repita a sincronização para main.

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 changeset

3. 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.md do 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? ​

BumpQuando usarExemplo
patchBugfix, ajuste de comportamento sem nova feature, melhora interna, bump por dependência.Corrigir cálculo de carência pós-EC 103
minorNova funcionalidade compatível, novo endpoint, novo cálculo, novo componente público.Nova tela de benefício de transição em prev-tc
majorBreaking 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 status

Mostra 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 push

Vá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:

  1. Branch a partir de main e aplique a correção.
  2. Crie o changeset: pnpm changeset.
  3. Rode pnpm changeset version localmente — isso consome o .changeset/*.md, atualiza o CHANGELOG.md e bumpa o package.json dos pacotes afetados.
  4. Comite a correção, o CHANGELOG.md atualizado e os bumps em um único MR direto para main.
  5. Mergeie → o pipeline em main detecta as mudanças em CHANGELOG.md e cria os jobs manuais deploy-prd/*. Clique para deployar.
  6. Sincronize a correção de main de volta para develop por 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 em apps/docs-tec/site/.
  • Scripts de desenvolvimento — em scripts/ da raiz ou dentro de apps/*, 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:

  1. Validar dev — uma conferência do que mudou antes da homologação.
  2. Promover para stg — abrir o pipeline correspondente no GitLab e clicar em "Run" no job deploy-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:

  1. Crie um MR com a correção, incluindo novo changeset.
  2. Mergeie → bot atualiza o MR "Version Packages".
  3. Mergeie o "Version Packages" atualizado → dev é redeployado automaticamente com a correção.
  4. Valide novamente em dev.
  5. 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 .md em .changeset/.
  • Confira no pipeline GitLab se o job release rodou 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.