prepare-core-kit-release

Preparar Release do Core Kit

Prepara o repositório bottlerocket-core-kit para um novo release, incrementando a versão no Twoliter.toml e atualizando o CHANGELOG.md.

Propósito

Automatizar o workflow de preparação de release para o bottlerocket-core-kit:

• Incrementar a versão do release no Twoliter.toml
• Gerar entradas de changelog a partir do histórico do git
• Criar commits formatados corretamente para o release

Quando Usar

• Preparando um novo release do bottlerocket-core-kit
• Necessidade de atualizar o changelog com mudanças recentes
• Criando commits de release com a formatação adequada

Pré-requisitos

• Trabalhar em um grove com bottlerocket-core-kit baixado
• Histórico do git disponível com merge commits e referências de PRs
• Conhecimento da versão alvo do release

Procedimento

Workflow de Release

IMPORTANTE: O processo de release requer DOIS commits em ordem estrita:

Commit 1: Bump de Versão (DEVE vir primeiro)

Atualize Twoliter.toml para definir a nova versão do release:

# Em Twoliter.toml, atualize:
release-version = "X.Y.Z"

Comando de commit:

git add Twoliter.toml && git commit -s -S -m "twoliter: bump kit version to vX.Y.Z"

Commit 2: Atualização do Changelog (DEVE vir em segundo)

Atualize CHANGELOG.md com as mudanças da nova versão.

Comando de commit:

git add CHANGELOG.md && git commit -s -S -m "changelog: update for vX.Y.Z"

1. Identificar Novos Commits

• Encontre commits desde a última entrada do changelog usando: git log --oneline <ultima_tag_versao>..HEAD
• Se não houver tags, use: git log --oneline --since="<data_ultimo_release>"

2. Encontrar Referências de PRs

• Analise merge commits para encontrar números de PRs: git log --merges --oneline <ultima_tag_versao>..HEAD
• Procure por padrões como "Merge pull request #XXX" nas mensagens de commit
• Faça referência cruzada dos hashes de commit com os merge commits dos PRs

3. CRÍTICO: Verificar Conteúdo dos PRs

SEMPRE verifique quais pacotes/alterações estão em cada PR checando os arquivos realmente modificados:

git show <hash_do_merge_commit> --stat

NÃO confie em:

• Resumos de mensagens de commit sozinhos
• Nomes de branches dos PRs
• Suposições sobre o que um PR contém

CUIDADO COM PRs MISTOS: Um único PR pode conter TANTO mudanças de primeira parte QUANTO atualizações de pacotes de terceiros. Você deve criar entradas de changelog separadas para cada tipo de mudança do mesmo PR.

Exemplo de PR misto (PR #760):

git show 70609d6a --stat
# Mostra mudanças em:
#   sources/host-ctr/...          <- Mudança de primeira parte (resolver host-ctr)
#   packages/amazon-vpc-cni-plugins/...  <- Atualização de terceiros
#   packages/ecs-agent/...        <- Atualização de terceiros

Este PR requer DUAS entradas de changelog:

1. Mudanças no SO: "Substituir amazon-ecr-containerd-resolver pelo resolver Docker em host-ctr ([#760])"
2. Atualizações de Pacotes de Terceiros: "Atualizar amazon-vpc-cni-plugins, ecs-agent ([#760])"

Exemplo de verificação correta:

# Para o merge commit 9656d841 (PR #795):
git show 9656d841 --stat
# Mostra mudanças em: libcap, liburcu, libxcrypt, readline
# NÃO o que o nome da branch ou resumo poderia sugerir

4. Diretrizes de Estilo do Changelog

Formato do Cabeçalho de Versão

# v<VERSÃO> (<AAAA-MM-DD>)

Hierarquia de Seções

1. Mudanças no SO - Atualizações do sistema central e pacotes de primeira parte
   • Atualizações de pacotes de primeira parte (com subitens detalhados)
   • Subseção Atualizações de Pacotes de Terceiros para pacotes externos
2. Mudanças na Build - Mudanças no sistema de build, ferramentas e infraestrutura
3. Mudanças no Orquestrador - Mudanças específicas de orquestração de contêineres
   • Subseção Kubernetes quando aplicável

Formato de Entrada

• Use marcadores com referências de PRs: - Descrição ([#XXX])
• Para pacotes de primeira parte, inclua subitens detalhados quando apropriado
• Para atualizações de pacotes de terceiros: NÃO inclua números de versão
  • CORRETO: - Atualizar \docker-cli-29`, `docker-engine-29` ([#785])`
  • ERRADO: - Atualizar \docker-cli-29` para v29.0.4, `docker-engine-29` para v29.0.4 ([#785])`
• Para patches/correções, use "Corrigir" em vez de "Atualizar":
  • CORRETO: - Corrigir \containerd-2.1` para atualizar GRPC ([#801])`

Regras de Categorização

• Pacotes de primeira parte: Código específico do Bottlerocket e dependências internas
• Pacotes de terceiros: Bibliotecas e ferramentas externas (glibc, docker-engine, etc.)
• Mudanças na build: Qualquer coisa que afete o sistema de build, CI/CD ou ferramentas de desenvolvimento
• Mudanças no orquestrador: Kubernetes, ECS ou outros recursos de orquestração de contêineres

5. Verificações de Qualidade

• Garanta que todas as entradas tenham referências de PRs no formato ([#XXX])
• Verifique formatação e indentação consistentes
• Agrupe mudanças relacionadas para evitar entradas repetitivas
• Mantenha ordem cronológica dentro das seções
• Verifique se os cabeçalhos das subseções correspondem aos padrões existentes
• VERIFIQUE o conteúdo real de cada PR antes de escrever a entrada

Validação

Comandos de Validação

• Verifique o intervalo do git log: git log --oneline <intervalo>
• Cheque merge commits: git log --merges --grep="pull request" <intervalo>
• Cheque o conteúdo dos PRs: git show <hash_merge> --stat
• Valide se os números dos PRs existem no repositório

Uma preparação de release bem-sucedida inclui:

• Dois commits na ordem correta (bump de versão primeiro, changelog segundo)
• Twoliter.toml com release-version atualizado
• CHANGELOG.md com nova seção de versão e data correta
• Todas as entradas com referências de PRs no formato ([#XXX])
• Atualizações de pacotes de terceiros NÃO incluem números de versão
• Commits estão assinados (flags -s -S)

Problemas Comuns

Referências de PRs Ausentes

Se merge commits não mostrarem números de PRs, verifique:

git log --merges --oneline | head -20

Procure por padrões "Merge pull request #XXX".

Categorização Incorreta de Pacotes

Sempre verifique com git show <hash> --stat para ver os arquivos reais alterados antes de categorizar como primeira parte vs. terceiros.

Número de Versão em Atualizações de Terceiros

Lembre-se: entradas de atualização de pacotes de terceiros NÃO devem incluir números de versão, apenas nomes de pacotes.

Exemplo de Estrutura de Saída

# v12.3.0 (2026-01-20)

## Mudanças no SO
- Substituir `amazon-ecr-containerd-resolver` pelo resolver Docker em `host-ctr` ([#760])
- Adicionar suporte ao daemon de controle MPS em `nvidia-k8s-device-plugin` ([#789])

### Atualizações de Pacotes de Terceiros
- Atualizar `docker-cli-29`, `docker-engine-29` ([#785])
- Corrigir `containerd-2.1` para atualizar GRPC ([#801])
- Atualizar `libnvme`, `xfsprogs`, `nvme-cli`, `makedumpfile`, `keyutils`, `e2fsprogs` ([#794])
- Atualizar `readline`, `libxcrypt`, `liburcu`, `libcap` ([#795])

[#760]: https://github.com/bottlerocket-os/bottlerocket-core-kit/pull/760
[#785]: https://github.com/bottlerocket-os/bottlerocket-core-kit/pull/785
[#789]: https://github.com/bottlerocket-os/bottlerocket-core-kit/pull/789
[#794]: https://github.com/bottlerocket-os/bottlerocket-core-kit/pull/794
[#795]: https://github.com/bottlerocket-os/bottlerocket-core-kit/pull/795
[#801]: https://github.com/bottlerocket-os/bottlerocket-core-kit/pull/801