Fluxo de Release com Changesets

A Fábrica de Cálculos usa Changesets para versionar pacotes e gerar CHANGELOG.md de forma automatizada. Toda alteração em apps ou packages passa por esse fluxo — sem changeset, o pipeline não detecta o que buildar e deployar.

Visão geral

flowchart TD
    A[branch de feature] -->|PR para develop| B[develop]
    B -->|bot abre PR| C["PR '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 deploy prd]
    F -->|publicação manual<br/>pelo admin| G[comunicado de release<br/>visível ao usuário]

Três ambientes, três níveis de automação:

Ambiente	Quem acessa	Como é deployado
dev	Equipe interna na rede do TRF3 (local ou VPN)	Automático após merge do PR "Version Packages" em develop
stg	Usuários piloto selecionados (acesso público)	Manual — clique no botão "Run" do job deploy-stg/* no pipeline mais recente
prd	Todos os usuários	Manual — merge develop → main

O ambiente dev é seu preview rápido: a equipe testa, corrige, valida sem afetar usuários externos. O acesso é restrito à rede interna do TRF3 — você precisa estar trabalhando localmente na infraestrutura ou conectado pela VPN institucional. Quando estiver satisfeito, promove para stg no GitLab UI. Só depois de validar em stg é que promove para prd.

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

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.

git add .changeset/
git commit -m "feat(prev-tc): adiciona suporte a benefício de transição"

7. Abra o PR para develop

Pronto. Daqui em diante, o bot e o CI tomam conta.

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 PR

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 PR é 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 PR. Adicione em commit novo no mesmo PR:

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 PR 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 develop com main para não perder o hotfix:

git checkout develop
git merge main
git push

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 PR "Version Packages" é mergeado em develop, o dev é deployado automaticamente — você não precisa fazer nada. Mas stg exige um clique manual no GitLab.

Quem é responsável

A pessoa que mergeia o PR "Version Packages" assume duas tarefas pós-merge:

1. Validar dev — um smoke test do que mudou. O ambiente dev é restrito à rede interna do TRF3 (local ou VPN); é o lugar para testar, descobrir bugs e corrigir antes de expor a usuários externos.
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 PR com a correção, incluindo novo changeset.
2. Mergeie → bot atualiza o "Version Packages" PR.
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 PR "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 PR em develop, em alguns minutos um PR chamado "Version Packages" aparece (ou é atualizado, se já existir um aberto). Esse PR lista todos os pacotes que serão bumpados, com os textos dos changesets virando CHANGELOG.md.

Se o PR 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 PR "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 PR atualizado.