Release notes (notas da versão) contam aos clientes o que mudou numa versão do produto, em linguagem simples e agrupado por tipo: novidades, melhorias, correções e o que vai deixar de existir. O changelog interno registra tudo, inclusive mudanças técnicas e referências de tickets, para dar rastreabilidade. O formato padrão de changelog organiza as versões num arquivo único, da mais recente para a mais antiga.
Como usar
- Informe o produto, a versão (de preferência MAJOR.MINOR.PATCH) e a data.
- Liste as mudanças com tipo, descrição, público (clientes ou interno) e referência do ticket.
- Escreva o destaque da versão e, se houver, a ação que os clientes precisam tomar.
- Leia os avisos: termo técnico em nota de cliente e item obsoleto sem substituto.
- Exporte em Markdown para o blog de novidades, a central de ajuda ou o arquivo CHANGELOG.
O que cada campo pede
| Campo | O que preencher |
|---|---|
| Produto | Ex.: Agenda Fácil |
| Versão | De preferência no formato MAJOR.MINOR.PATCH. |
| Data | Opcional. O formato AAAA-MM-DD funciona em qualquer idioma. |
| Tipo | Novo, melhoria, correção ou obsoleto. |
| Descrição | Ex.: lembrete por mensagem 2 horas antes do horário |
| Público | Clientes veem nas notas; interno fica só no changelog. |
| Referência | Código do ticket (opcional, não aparece para clientes). |
| Destaque da versão | A frase que abre as notas (opcional). |
| Ação necessária | O que o cliente precisa fazer, se precisar (opcional). |
Exemplo
A versão 2.4.0 de um app fictício de agendamento tem 6 mudanças, 5 delas para clientes. As notas abrem com o destaque do agendamento recorrente e resumem: 2 novidades, 1 melhoria, 1 correção e 1 item que deixa de existir. O ajuste técnico de cache fica só no changelog interno, com a referência do ticket. A exportação no formato antigo aparece em "vai deixar de existir", com o substituto e o prazo, e uma ação necessária avisa quem precisa migrar para CSV até 31/12.
Quando usar
- A cada versão publicada, para avisar os clientes sem copiar a lista de tickets.
- Para manter um arquivo de changelog organizado sem escrever a mesma coisa duas vezes.
- Quando uma funcionalidade vai deixar de existir e os clientes precisam saber o que fazer.
- Para revisar se as notas para clientes estão sem jargão técnico antes de publicar.
Perguntas frequentes
Qual a diferença entre release notes e changelog?
As release notes são para clientes: poucas linhas, linguagem simples, foco no que muda para quem usa. O changelog é o registro completo de mudanças, inclusive técnicas, pensado para o time e para quem integra com o produto.
O que é o formato padrão de changelog?
É uma convenção aberta para arquivos de changelog: cada versão vira uma seção "[versão] - data", com as mudanças agrupadas em adicionado, alterado, corrigido e obsoleto, da mais recente para a mais antiga.
O que é versionamento MAJOR.MINOR.PATCH?
É um jeito de numerar versões: o primeiro número sobe quando há mudança que quebra compatibilidade, o segundo quando há novidade compatível e o terceiro quando há só correção. A ferramenta avisa quando a versão não segue esse formato.
Como escrever notas em linguagem de cliente?
Diga o que muda para quem usa, não o que o time fez por dentro. Troque "ajuste na API" por "a agenda abre mais rápido", tire códigos de ticket e use frases curtas.
Como comunicar algo que vai deixar de existir?
Diga o que deixa de funcionar, até quando, o que usar no lugar e o que a pessoa precisa fazer. A ferramenta avisa quando um item obsoleto não diz o substituto nem o prazo.
Com que frequência publicar notas da versão?
A cada versão que muda algo visível para os clientes. Times com entrega contínua costumam agrupar as mudanças em notas semanais ou quinzenais.