Release notes do GitHub: gere e depois torne legíveis
7 min de leitura
Release notes do GitHub são a descrição anexada a uma release na página Releases do repositório, e o GitHub consegue escrever um primeiro rascunho delas para vocês a partir dos pull requests integrados desde a tag anterior. O rascunho é uma lista de títulos de pull requests agrupados por label, com uma linha de contribuidores e um link de comparação. Ele é preciso, completo e escrito para as pessoas que integraram os pull requests. Transformá-lo em algo que um usuário do projeto consiga ler exige um arquivo .github/release.yml e uma passada curta de edição, e os dois são descritos abaixo.
| Forma de produzir as notas | Onde roda | O que você recebe |
|---|---|---|
| Botão “Generate release notes” | Formulário de release na interface web | Títulos de PR desde a última tag, agrupados pelas categorias do release.yml |
gh release create v1.4.0 --generate-notes | GitHub CLI, local ou CI | O mesmo rascunho, criado junto com a release em um comando |
POST /repos/{owner}/{repo}/releases/generate-notes | REST API | O rascunho como texto, sem criar uma release, para o seu próprio pipeline |
| release-please, semantic-release, conventional-changelog | GitHub Actions ou um job de release | Notas a partir das mensagens de commit em vez dos títulos de PR, mais o salto de versão e um CHANGELOG.md |
| Escrita à mão | O formulário de release | O que você digitar, sem link de volta para os pull requests |
Como gerar release notes automaticamente no GitHub?
Abra o formulário de release, escolha ou crie a tag e clique em “Generate release notes”. O GitHub encontra a tag da release anterior, lista todo pull request integrado no branch alvo entre as duas e escreve uma linha por pull request com título, autor e número. Na linha de comando, gh release create <tag> --generate-notes faz a mesma coisa e publica a release em um só passo; --notes-start-tag sobrescreve a tag anterior a partir da qual o intervalo começa.
O recurso trabalha a partir de pull requests, então um repositório que integra direto em main sem pull requests recebe um rascunho vazio. Squash merges funcionam bem, porque o pull request continua existindo. Merge commits de um branch de vida longa em main produzem uma linha para o pull request que fez o merge, sem nenhum dos pull requests integrados naquele branch antes. Se o intervalo parece errado, a causa comum é uma tag anterior ausente ou fora de ordem; o gerador usa a release mais recente do branch alvo, e uma tag sem release anexada é ignorada.
A página do GitHub Docs sobre release notes geradas automaticamente cobre o botão, e o manual do gh release create cobre as flags da CLI.
O que o release.yml muda?
O .github/release.yml diz ao gerador quais pull requests deixar de fora e como agrupar o resto. Sem ele, todo pull request cai em uma lista só, Dependabot incluído. Com ele, os pull requests são separados em categorias por label, e o ruído com label ou de autoria de bots desaparece.
# .github/release.yml
changelog:
exclude:
labels:
- skip-changelog
authors:
- dependabot
- renovate
categories:
- title: Breaking changes
labels:
- breaking-change
- title: New
labels:
- enhancement
- title: Fixed
labels:
- bug
- title: Other changes
labels:
- "*"Três regras que vale conhecer. As categorias são comparadas em ordem, então um pull request com breaking-change e bug vai para o primeiro título que casar. O coringa "*" é obrigatório se vocês querem que pull requests sem label apareçam; sem ele, são descartados em silêncio. E o arquivo só afeta o que o gerador escreve, então mudá-lo não toca notas que já existem. Equipes que já etiquetam pull requests para uma verificação de changelog no CI podem reaproveitar as mesmas labels aqui.
Por que as release notes geradas pelo GitHub ficam ruins de ler?
Porque um título de pull request é escrito para quem revisa, antes de a mudança estar pronta, e descreve o código. “Refatorar worker de export para usar streaming” é um bom título de pull request e uma release note inútil, porque quem lê a release quer saber que exportações acima de 100 MB não estouram mais o tempo limite.
A segunda razão é que todo pull request integrado tem o mesmo peso. Uma correção de erro de digitação de uma linha fica ao lado de um novo fluxo de autenticação, na ordem em que foram integrados. O leitor precisa varrer a lista inteira para achar as três linhas que o afetam.
A terceira é que o rascunho não tem abertura. Uma lista de quarenta linhas sem uma frase acima não diz a ninguém se esta release é segura de adotar, exige uma migração ou existe só para fixar uma dependência.
O que a passada de edição deve mudar?
Mantenha a lista gerada e acrescente a ela, em vez de reescrever do zero. A lista é a trilha de auditoria; os números dos pull requests são a forma de alguém rastrear uma linha até o diff. A edição acrescenta as partes que o gerador não tem como saber.
- Escreva duas ou três frases no topo. Para que serve esta release, se atualizar exige alguma ação e o que ler primeiro. Se há um breaking change, diga isso na primeira linha.
- Reescreva as linhas que importam para as pessoas pelo lado do leitor: o sintoma que sumiu, o que agora dá para fazer, a configuração que mudou de lugar. Deixe o número do pull request no fim da linha. Como escrever release notes traz a forma completa; release notes de correção de bugs cobre as linhas de correção em particular.
- Mova para uma seção própria tudo o que o leitor precisa fazer, com o comando ou a configuração exata. Um breaking change enterrado na lista “Other changes” é um ticket de suporte dali a uma semana.
- Não apague nada da lista gerada. Recolha-a sob um título “Lista completa de mudanças” se for longa, mas mantenha-a, porque os contribuidores do projeto a usam.
Feitas assim, as release notes do GitHub levam uns dez minutos de edição em uma release típica, e as notas servem aos dois públicos: o resumo no topo para usuários, a lista abaixo para contribuidores.
A release do GitHub deve ser o seu changelog?
Só se todo mundo que precisa saber de uma mudança já lê a página Releases. Para uma biblioteca consumida por desenvolvedores via gerenciador de pacotes, isso costuma ser verdade, e a página Releases mais um CHANGELOG.md no repositório bastam. Para um produto com usuários que nunca abrem o GitHub, não: a página da release é escrita no nível errado, mora em uma URL voltada a desenvolvedores e não pode ser assinada por quem não tem conta no GitHub.
O padrão que se sustenta é tratar a release do GitHub como o registro voltado a desenvolvedores e o changelog do produto como o registro voltado ao leitor, com a release linkando para a entrada do changelog. Tags do Git, releases e o changelog cobre como os três registros se alinham. Se o changelog do produto é gerado a partir dos mesmos commits, um gerador de changelog dá um rascunho para esse lado também, e a divisão em changelog vs release notes explica qual detalhe pertence a cada um.
Como versionar as próprias release notes?
Uma release publicada no GitHub pode ser editada a qualquer momento, e a edição não deixa histórico visível na página. Para a maioria dos projetos isso não é problema. Para projetos em que as notas são um registro do qual compliance ou clientes dependem, dois hábitos ajudam: manter o texto canônico no repositório (o CHANGELOG.md, ou uma pasta docs/releases/) e fazer o corpo da release apontar para ele, e ativar releases imutáveis no repositório se o seu plano oferece isso, o que trava a tag e os assets depois de publicados. O GitHub Docs sobre gerenciar releases descreve rascunhos, pre-releases e o rótulo “latest”, atribuído pela ordem de versão semântica a menos que vocês o definam à mão.
FAQ
As release notes do GitHub podem ser geradas automaticamente?
Sim. O botão “Generate release notes” no formulário de release, a flag --generate-notes do gh release create e o endpoint REST generate-notes produzem um rascunho a partir dos pull requests integrados desde a tag da release anterior. Um arquivo .github/release.yml controla agrupamento e exclusões.
Por que minhas release notes geradas estão vazias? O gerador lista pull requests, então commits diretos no branch não aparecem, e o intervalo começa na release mais recente do branch alvo, não na tag mais recente. Confira se a release anterior existe e se as mudanças entraram por pull requests.
O release.yml se aplica a releases que já existem? Não. Ele só molda notas geradas depois que o arquivo está no lugar. Os corpos das releases existentes ficam como estavam até alguém editá-los.
Devo usar release notes do GitHub ou um CHANGELOG.md? Os dois, se o projeto tem contribuidores e usuários. A página da release é onde desenvolvedores olham e onde os assets moram; o arquivo no repositório sobrevive a uma saída do GitHub e pode ser lido offline. Gere as release notes, mantenha o arquivo atualizado e linke um ao outro.
As afirmações técnicas deste artigo não foram revisadas de forma independente. Se algo estiver errado, avise a gente e vamos corrigir.