Release notes de software: o que são e o que incluir

Release notes de software são o documento que acompanha uma versão do software e diz ao leitor o que mudou nela, a quem a mudança afeta e o que, se for o caso, ele precisa fazer. São escritas uma vez por release e lidas por quem decide se vai atualizar, por quem confere se um problema que encontrou foi corrigido e por quem dá suporte ao produto. As boas são curtas, específicas da versão e honestas sobre qualquer coisa que quebre.

O que são release notes de software?

São um resumo datado e versionado de uma release. Uma release note responde três perguntas para um leitor que não estava na sala: o que mudou, isso me afeta e preciso agir. O histórico completo do projeto é o changelog, e o log de commits é para quem escreveu o código.

Os mesmos fatos podem aparecer numa entrada de changelog e nas release notes. A diferença é a seleção e o público: o changelog lista toda mudança relevante, enquanto as release notes abrem com as que o leitor vai notar e as explicam. Changelog vs release notes traça essa linha em detalhe.

O que as release notes de software devem incluir?

Inclua a versão e a data, um resumo de um parágrafo e depois as mudanças agrupadas pelo que o leitor pode fazer com elas. Para cada mudança, diga o que é diferente nos termos do leitor, quem é afetado e se é preciso agir.

Um conjunto completo tem estas partes:

1. Número da versão e data da release. Use o formato das suas tags, para o leitor casar as notas com um build.
2. Um resumo. Duas ou três frases: para que serve esta release e se atualizar exige algo do leitor.
3. Novos recursos e melhorias. O que o leitor agora pode fazer, não o que o código agora contém.
4. Correções. O sintoma que sumiu e a versão em que ele começou.
5. Breaking changes e depreciações. O que deixa de funcionar, quando e o que usar no lugar. Coloque isto primeiro, se houver.
6. Problemas conhecidos. Qualquer coisa lançada que você sabe que não está certa, com uma solução alternativa, se existir.
7. Requisitos e passos de atualização. Plataformas suportadas, versões mínimas, comandos de migração.

Deixe de fora refatorações, atualizações de dependência sem efeito visível e tickets internos. Se o leitor não consegue notar a mudança, ela pertence ao histórico do git. Como escrever release notes cobre a redação e a ordem.

Como é uma release note de software?

Aqui está uma curta, para uma ferramenta de linha de comando inventada. O formato importa mais que o conteúdo.

## 2.4.0 (2026-10-08)

Exportações mais rápidas e um breaking change no arquivo de
configuração. Atualizar exige editar uma linha em `tool.yml`.

### Breaking
- `output:` em `tool.yml` agora é `export.path:`. Configs antigas
  falham com "unknown key". Renomeie a chave; nada mais muda.

### Novo
- As exportações vão direto para o disco, então arquivos acima de
  100 MB não dão mais timeout.

### Corrigido
- A busca voltou a funcionar com consultas que têm hífen. Quebrada
  desde a 2.3.0.

### Problemas conhecidos
- Caminhos do Windows com mais de 260 caracteres ainda falham. Use
  um diretório de saída mais curto por enquanto.

O breaking change vem primeiro, com o texto exato do erro que o leitor vai ver, porque as pessoas pesquisam mensagens de erro. A correção nomeia a versão em que quebrou, para o leitor associar a data em que o problema dele começou. O problema conhecido traz uma solução alternativa, o que é melhor que o silêncio. Exemplos de release notes tem mais redações para cada tipo de entrada.

Como as release notes de software mudam para cada público?

Mantenha uma única fonte da verdade e escreva uma versão por público. Os fatos não mudam, mas o nível de detalhe sim. Clientes querem o benefício em uma linha, administradores querem requisitos e problemas conhecidos, desenvolvedores querem nomes e versões exatos, e o suporte quer saber o que dizer quando chegar um ticket.

Para produtos de API, a versão para desenvolvedores exige mais cuidado, porque uma mudança que para você é uma pequena correção pode ser uma queda para quem chama. Changelog de API e breaking changes cobrem esse público. Para a versão interna, release notes internas descreve o que suporte e vendas precisam e os clientes não.

Onde publicar as release notes de software?

Publique onde o leitor já está quando faz a pergunta. Para um app mobile, é a página da loja, onde a plataforma oferece um campo de release notes para cada versão; a Apple documenta como fornecer release notes para builds. Para um produto web, é uma página de changelog com link a partir do app. Para uma biblioteca, é a página de release e um arquivo no repositório, como descrito em release notes do GitHub.

Mantenha cada versão numa URL estável para o suporte poder linkar, e guarde as versões antigas. Quem está na versão 2.2 precisa também das notas da 2.3 e da 2.4. Se quiser uma estrutura inicial, o template de release notes traz títulos para copiar.

Qual deve ser o tamanho das release notes?

O que a mudança pede, e não mais. Uma release de patch pode ter três linhas. Uma release major com migração precisa de uma página, e provavelmente de um guia de migração separado, com link a partir das notas. O teste é se um leitor que passa os olhos pela primeira tela sabe se a release o afeta. Se não sabe, suba o resumo e corte o resto. Melhores práticas de release notes lista o que se sustenta e o que é só hábito.

FAQ

O que são release notes de software? São um resumo versionado do que mudou em uma release de um software, escrito para quem o usa ou dá suporte. Cobrem novos recursos, correções, breaking changes e qualquer coisa que o leitor precise fazer.

Qual é a diferença entre release notes e changelog? O changelog é o registro corrente e completo das mudanças relevantes. As release notes são uma mensagem sobre uma release, selecionada e reescrita para leitores que decidem se vão atualizar. Muitas equipes publicam a entrada do changelog de uma versão como suas release notes.

Quem escreve as release notes de software? Em geral o gerente de produto, um redator técnico ou o engenheiro que entregou a mudança, com alguém revisando o tom. O melhor resultado vem quando quem está mais perto da mudança faz o rascunho e uma segunda pessoa edita pensando no leitor.

Releases menores precisam de release notes? Sim, curtas. Até uma release de patch deve dizer o que foi corrigido e se o leitor precisa agir. Uma nota de uma linha é melhor que nenhuma, porque “correções de bugs e melhorias” não diz nada ao leitor.

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