Notas de versão na prática

Como escrever release notes que as pessoas realmente leem

7 min de leitura atualizado em

Para escrever release notes que as pessoas leem, responda uma pergunta por entrada: o que o leitor pode fazer agora que antes não podia, e o que ele precisa fazer a respeito. Coloque qualquer coisa com prazo em primeiro lugar, nomeie quem é afetado, diga “nenhuma ação necessária” quando for verdade, e pule releases que não têm nada a dizer. Tudo mais nesta página é essa regra aplicada.

Uma release note montada assim, uma linha por seção:

## 2.4.0 (18 de outubro de 2026)

Incompatível: GET /v1/export será removido em 1º de dezembro de
  2026. Use GET /v2/exports.
Novo: agende um relatório para chegar por e-mail toda segunda.
Melhorado: painéis com mais de 50 gráficos carregam em cerca da
  metade do tempo.
Corrigido: exports em CSV não perdem mais a última linha de
  relatórios muito grandes.

A versão completa, com uma linha de resumo e espaço para cada seção, é o template de release notes. Este artigo trata de escrever as notas de uma release; os hábitos que as mantêm boas release após release estão em melhores práticas de release notes.

Correções de bugs e melhorias de desempenho.

Todo produto já publicou isso uma vez. A causa raramente é preguiça: isso é o que se obtém quando release notes são escritas de dentro, por alguém que passou duas semanas no diff e não consegue mais ver quais partes importariam para um estranho. Um tom melhor não vai resolver isso; responder à pergunta, sim.

O que release notes deveriam incluir?

Release notes deveriam incluir, para cada mudança que merece menção: o que o leitor pode fazer agora, quem é afetado, o que ele deve fazer a respeito (incluindo “nada”), e quando qualquer coisa com prazo entra em vigor. Não deveriam incluir números de tickets internos, nomes de componentes que só a equipe usa, ou um número de versão como único título.

IncluirDeixar de fora
O resultado, nos termos do leitorA implementação, nos termos da equipe
Quem é afetado, por plano, cargo ou versão de API“Alguns usuários”
A ação necessária, ou “nenhuma ação necessária”Silêncio, que o leitor preenche com o pior cenário
Uma data para qualquer coisa com prazoUm número de versão no lugar de uma data
Um link para a doc que explicaUm link para o pull request
Bugs que as pessoas relataram, e o limite que foi elevadoIds de tickets internos
A seção chata, uma linha cada, no finalA seção chata misturada com as novidades

A separação entre uma release note e uma entrada de changelog é o que torna essa lista possível: o changelog guarda tudo, então as notas podem deixar coisas de fora. Exemplos comentados de cada tipo de entrada estão reunidos em exemplos de release notes, e as correções, as entradas mais mal escritas, têm guia próprio em release notes de correção de bugs. A mesma ideia é o primeiro princípio do Keep a Changelog: changelogs são para humanos, não para máquinas.

A pergunta que cada entrada responde

O que o leitor pode fazer agora que antes não podia, e o que ele precisa fazer a respeito?

Se uma entrada não consegue responder isso, ela pertence ao changelog e não às release notes. As duas metades importam. A primeira metade é o valor. A segunda metade é a que as equipes esquecem, e é a que gera tickets de suporte quando falta.

Dois exemplos da segunda metade fazendo trabalho de verdade:

  • “Webhooks existentes continuam funcionando até 1º de novembro. Depois dessa data, payloads sem assinatura serão rejeitados.”
  • “Nenhuma ação necessária. Exports existentes são recodificados automaticamente na próxima vez que você os abrir.”

O segundo diz “nenhuma ação necessária” explicitamente. Essa frase vale a pena escrever toda vez, porque um leitor que não a encontra assume o pior.

Como release notes deveriam ser ordenadas?

Ordene-as por consequência para o leitor, nunca pela parte do sistema que mudou. Agrupar por API, painel, mobile e infraestrutura é o organograma de vocês, não o problema do leitor.

  1. Mudanças que quebram algo e qualquer coisa com prazo. Sempre em primeiro, mesmo que seja pequeno. Se um leitor para de ler depois de uma linha, essa é a linha que ele precisava ter lido. Se o prazo é um sunset, a entrada deveria soar como um aviso de depreciação.
  2. O que é novo e que eles vão querer. Um por parágrafo, com o resultado na primeira frase.
  3. O que melhorou. Bugs que foram relatados, limites que foram elevados, coisas que estavam lentas.
  4. Tudo mais, como lista. Atualizações de dependências, refatorações internas, texto menor. Uma linha cada. Ninguém lê essa seção, e ainda assim ela precisa estar lá, porque quem a procura realmente precisa dela.

A reescrita

Antes:

v4.2.0 Corrigido um problema em que o endpoint POST /exports retornava 500 intermitentemente sob carga. Refatorado o worker de export. Atualizado node-pg para 8.11. Melhorado o tratamento de erros no serializador CSV.

Depois:

Exports não falham mais em contas grandes. Contas com mais de aproximadamente 50.000 linhas podiam receber um 500 ao iniciar um export, mais frequentemente no fim do mês. Isso foi corrigido, e exports de qualquer tamanho agora tentam novamente sozinhos em vez de falhar. Nenhuma ação necessária, e qualquer export que falhou na última semana pode simplesmente ser executado novamente.

Também na 4.2.0: node-pg 8.11, erros mais claros no serializador CSV.

Mesma release. A segunda nomeia a conta afetada, o momento em que foi pior, o que mudou, e o que fazer. A atualização de dependência não desapareceu, só deixou de ser o título. O artigo melhores práticas de release notes tem o resto das regras que essa reescrita segue, cada uma com o custo de pulá-la.

Coisas que vale a pena eliminar

  • “Estamos animados em anunciar.” O leitor ainda não está animado. Conquiste isso na próxima frase.
  • Números de tickets internos. PROJ-4471 não significa nada fora do tracker de vocês. Se a entrada precisa de uma referência, linke a página de docs.
  • Nomes de componentes que só a equipe de vocês usa. Se vocês renomearam o “pipeline de ingestão”, digam “importações”.
  • Um número de versão como único título. v4.2.0 é um rótulo de arquivamento, não um resumo.
  • Screenshots de uma página de configurações que ninguém jamais visitou. Mostre o que mudou, em uso.

Com que frequência release notes deveriam ser publicadas?

Publique quando algo aconteceu, não em um cronograma. Notas que chegam a cada release ensinam todo mundo a ignorá-las. Notas que chegam quando algo aconteceu são abertas. Está tudo bem, e geralmente é correto, lançar uma release sem nenhuma nota e deixar suas entradas rolarem para o próximo conjunto que tenha um título que valha a pena ler.

O changelog continua registrando tudo. Essa é a divisão de trabalho: o changelog é completo, as notas são seletivas. Se vocês mantiverem o changelog estruturado ao longo do caminho, escrever as notas se torna seleção e reescrita em vez de arqueologia. Publicar as notas é a etapa de comunicação de um processo de gerenciamento de releases e, como qualquer outra etapa, precisa de um responsável.

O template de release notes é a forma que usamos para a etapa de seleção, e exemplos de changelog reúne entradas de equipes cujo changelog é bom o suficiente para derivar notas dele.

Tudo isso assume uma página que você controla totalmente, sem limite de tamanho e com links que funcionam. Release notes para apps mobile cobre o que muda quando a superfície é uma listagem de App Store ou Play Store. Release notes de emergência cobre a outra exceção: o que muda quando não sobra tempo nenhum para seguir o processo normal de escrita. A mudança por trás dessas notas costuma ser um hotfix, uma correção lançada fora do ciclo normal de releases.

Versões de pré-lançamento também precisam de notas, escritas para quem testa: cada build beta recebe uma nota curta com as correções que vieram dos relatos dos testadores (teste alfa vs beta), e as notas de um release candidate começam no primeiro candidato e acompanham cada um dos seguintes.

Um teste antes de publicar

Leia as notas como alguém que esteve de férias por duas semanas e tem 40 segundos. Se, nesse tempo, essa pessoa não conseguir dizer se algo é exigido dela, as notas não estão prontas, por mais precisas que sejam. Para uma visão mais ampla do que são release notes de software e dos quatro públicos a que servem, veja release notes de software.

FAQ

Quanto tempo release notes deveriam ter? O tempo que as mudanças com consequências exigirem, e nem uma linha a mais. Uma release com uma mudança que quebra algo e duas melhorias são três parágrafos. Encher uma release tranquila para parecer substancial é como os leitores aprendem a pular as notas.

Quem deveria escrever release notes? A pessoa que entende a mudança, editada por alguém que não entende. A engenheira sabe o que mudou; a editora sabe o que um estranho vai entender errado. Escrever a entrada no momento do merge, enquanto a engenheira ainda se lembra, é a prática que torna isso barato.

Release notes deveriam incluir correções de bugs? Sim, as que alguém relatou ou sofreu. Declare o sintoma que o leitor viu, não a causa. “Exports com mais de 50.000 linhas falhavam” é uma correção que um leitor reconhece; “corrigida uma race condition no worker de export” é uma mensagem de commit.

Qual é a diferença entre release notes e um changelog? O changelog é o registro completo e contínuo; as release notes são a mensagem selecionada sobre uma release, escrita para pessoas que ainda não decidiram se isso as interessa. A resposta mais longa está em changelog vs release notes.


As afirmações técnicas deste artigo não foram revisadas de forma independente. Se algo estiver errado, avise a gente e vamos corrigir.

Relacionado na Changeloop: Modelo de notas de versão, Exemplos de changelog

changeloop
O time por trás de um changelog que fecha o loop. Os usuários pedem algo, sua equipe entrega, quem pediu fica sabendo.