Convenções de changelog
Convenções de changelog
Seção intitulada “Convenções de changelog”Esta página define o contrato que todos os repositórios públicos do NextPDF seguem ao registrar alterações e publicar releases. É uma referência de convenções; não define o comportamento dos pacotes. As notas de release de cada pacote e versão ficam no próprio CHANGELOG.md do respectivo repositório. Essas regras compartilhadas mantêm o resumo do changelog entre repositórios consistente e livre de vazamentos.
Conventional Commits 1.0.0
Seção intitulada “Conventional Commits 1.0.0”Todo assunto de commit usa type(scope): description. O type é um destes:
| Tipo | Significado | Visível ao usuário | Efeito na versão |
|---|---|---|---|
feat | Novo recurso | sim | incremento minor |
fix | Correção de comportamento | sim | incremento patch |
perf | Melhoria de desempenho sem alteração de comportamento | sim | incremento patch |
refactor | Reestruturação interna sem alteração observável | não | nenhum |
docs | Somente documentação | não | nenhum |
test | Somente testes | não | nenhum |
build / ci | Somente build ou pipeline | não | nenhum |
chore | Manutenção, dependências ou ferramental | não | nenhum |
revert | Reversão de um commit anterior | depende | depende |
Uma breaking change usa um ! depois do tipo ou do escopo (feat(api)!: …) ou um rodapé BREAKING CHANGE:. Qualquer um desses marcadores eleva a versão para major de acordo com o Semantic Versioning. Registre correções relevantes para segurança para que possam aparecer na coluna Security do resumo entre repositórios.
Semantic Versioning 2.0.0
Seção intitulada “Semantic Versioning 2.0.0”Os incrementos de versão são mecânicos. Um release que contenha qualquer breaking change é major. Caso contrário, um release que contenha qualquer feat é minor. Caso contrário, um release que contenha qualquer fix ou perf é patch. Pacotes pré-1.0 podem incrementar o minor em caso de breaking change, conforme o SemVer §4. O commit ainda traz o marcador de breaking change para que o resumo permaneça preciso.
Agrupamento do Keep a Changelog
Seção intitulada “Agrupamento do Keep a Changelog”O CHANGELOG.md de cada repositório segue o Keep a Changelog 1.1.0: as entradas são agrupadas por versão lançada em Added, Changed, Deprecated, Removed, Fixed e Security. Uma seção [Unreleased] pode conter notas em andamento no repositório, mas o resumo entre repositórios conta apenas versões com tag e lançadas. Trabalho não lançado nunca aparece no índice público.
Como o resumo entre repositórios é derivado (e mantido livre de vazamentos)
Seção intitulada “Como o resumo entre repositórios é derivado (e mantido livre de vazamentos)”A tabela de resumo no índice do changelog é produzida lendo, em modo somente leitura, o histórico de Conventional Commits de cada repositório na sua tag lançada mais recente e contando categorias. As regras de derivação são deliberadamente restritas para impedir que detalhes internos escapem:
- Contagens, não conteúdo. Somente o número de commits por tipo visível ao usuário é informado. Nenhum assunto, corpo, rodapé ou hash de commit é renderizado.
- Apenas tipos visíveis ao usuário.
docs,test,ci,choreerefactorsão excluídos porque não alteram nada observável para um consumidor do pacote. - Apenas lançados. Um commit só entra na contagem depois de se tornar parte de um release com tag de um pacote público.
- Sem identificadores. Referências internas a issue, ticket, ciclo, wave ou item de trabalho que possam aparecer em um escopo de commit privado nunca são expostas, porque o texto do escopo em si nunca é renderizado. Somente o tipo é lido.
- Sem atribuição de automação. Trailers de automação de contribuidores não são lidos nem exibidos.
Por esse motivo, o changelog público é um resumo por categoria com links para o CHANGELOG.md de cada pacote, não um feed agregado de commits. O resumo é livre de vazamentos internos por construção. O texto autoritativo do release permanece com o pacote responsável por ele.