Workflow de Release — SDK
Guia end-to-end para alterar pacotes @cactus-agents/*, publicar novas versões e atualizar os consumidores.
Visão geral
front-cactus-core (SDK) front-web-base (consumidor)
┌────────────────────────┐ ┌───────────────────────┐
│ 1. Alterar código │ │ │
│ 2. Rodar testes │ │ │
│ 3. Criar changeset │ │ │
│ 4. Commit + push main │ │ │
│ │ │ │ │
│ ▼ │ │ │
│ 5. CI cria PR versão │ │ │
│ 6. Merge PR │ │ │
│ │ │ │ │
│ ▼ │ │ │
│ 7. CI publica no │──────────▶│ 8. pnpm update │
│ GitHub Packages │ │ 9. Testar + commit │
└────────────────────────┘ └───────────────────────┘
Regra de ouro: sempre publicar o SDK primeiro, depois atualizar consumidores.
Passo a passo
1. Alterar e testar
cd front-cactus-core
# fazer alterações nos pacotes
pnpm build
pnpm test
2. Criar changeset
pnpm changeset
O CLI interativo pede:
- Quais pacotes foram alterados — selecionar com espaço
- Tipo de bump — patch / minor / major
- Descrição — resumo da mudança (aparece no CHANGELOG)
O changeset gera um arquivo .md em .changeset/ que deve ser commitado.
Quando usar cada bump
| Tipo | Quando usar | Exemplo |
|---|---|---|
| patch | Bug fix, melhoria interna sem mudar API | Corrigir header faltando |
| minor | Nova funcionalidade, novo export (backwards compatible) | Adicionar createAuthFromClient |
| major | Breaking change — assinatura mudou, export removido | Renomear createBrandConfig para outra coisa |
Para 0.x.y, semver trata minor como potentially breaking. Na prática, usamos minor para features novas e patch para fixes.
3. Commit e push
git add .
git commit -m "feat: descrição da mudança"
git push origin main
Ou, se preferir separar o changeset:
git add packages/
git commit -m "feat: descrição da mudança"
git add .changeset/
git commit -m "chore: add changeset"
git push origin main
4. CI cria PR de versão
O workflow release.yml detecta changesets pendentes e cria um PR automático:
- Título: "chore: version packages"
- Conteúdo: bump de versão nos
package.json+ CHANGELOG atualizado - Branch:
changeset-release/main
5. Revisar e mergear o PR
Verificar no PR:
- As versões foram bumpadas corretamente
- O CHANGELOG reflete as mudanças
Ao mergear, o CI executa pnpm run release que builda e publica os pacotes no GitHub Packages.
6. Atualizar consumidores
No front-web-base (e qualquer fork):
cd front-web-base
# Atualizar todos os pacotes @cactus-agents
pnpm update @cactus-agents/api-client @cactus-agents/auth @cactus-agents/brand @cactus-agents/types @cactus-agents/utils
# Verificar
pnpm build
pnpm dev # testar fluxos principais
# Commit
git add pnpm-lock.yaml package.json
git commit -m "chore: bump @cactus-agents/* to 0.x.0"
git push origin main
Desenvolvimento local (sem publicar)
Para iterar rapidamente entre SDK e base sem passar pelo ciclo de publish:
Opção 1: pnpm link (recomendado)
# No SDK, buildar o pacote alterado
cd front-cactus-core/packages/auth
pnpm build
pnpm link --global
# No consumidor, linkar
cd front-web-base
pnpm link --global @cactus-agents/auth
# Testar normalmente
pnpm dev
# Quando terminar, desfazer o link
pnpm unlink @cactus-agents/auth
pnpm install
Opção 2: file protocol (temporário)
No package.json do consumidor:
{
"@cactus-agents/auth": "file:../front-cactus-core/packages/auth"
}
Rodar pnpm install e testar. Reverter antes de commitar.
Nunca commite file: ou link: no package.json. Isso quebra o CI.
Troubleshooting
Pacote não encontrado após publish
O GitHub Packages pode levar alguns segundos para propagar. Tente:
# Limpar cache do pnpm
pnpm store prune
pnpm install --force
403 Forbidden no CI
O PAT de leitura (GH_PACKAGES_TOKEN) pode ter expirado. Ver GitHub Packages para instruções de renovação.
Changeset não detectado pelo CI
Verificar que o arquivo .changeset/*.md foi commitado e está presente no push para main. O workflow release.yml só roda em push para main.
Versão não bumpou
O PR de versão só é criado quando existem changesets pendentes. Se o PR já existe, ele é atualizado automaticamente com novos changesets.