Modelo de notas de versão

O modelo

Tudo entre colchetes é um espaço reservado. Todo o resto vale a pena manter, incluindo a ordem: os usuários procuram pela coisa que os afeta, então mudanças que quebram compatibilidade vêm primeiro e trabalho interno não aparece.

## [Produto] [versão] - [data]

[Uma frase dizendo para que serve este lançamento. Pule em lançamentos rotineiros.]

### Mudanças que quebram compatibilidade
- [O que quebrou, o que mudar e até quando. Link para os passos de migração.]

### Novo
- [Funcionalidade, descrita como resultado. "Fixe um filtro e reutilize-o",
  não "modelo SavedView adicionado".]

### Melhorado
- [O que ficou mais rápido, mais claro ou mais confiável, e aproximadamente quanto.]

### Corrigido
- [O sintoma que o usuário viu, não a causa no código.]

Se uma seção estiver vazia, apague o título. Uma seção Corrigido vazia dá a impressão de que nada foi corrigido, e um título sem nada embaixo faz os leitores pensarem que a página falhou ao carregar.

O mesmo modelo, preenchido

Assim ele fica com conteúdo real. Note que nenhuma entrada menciona um arquivo, um branch, um número de ticket ou uma pessoa, e a mudança que quebra compatibilidade começa com a ação que o leitor precisa tomar.

## Acme API 4.2 - 20 de agosto de 2026

A paginação agora é baseada em cursor em todos os endpoints de listagem.

### Mudanças que quebram compatibilidade
- `?page=` foi removido em todos os endpoints de listagem. Use o valor
  `nextCursor` da resposta anterior. `?page=` retorna 400 após
  1 de outubro de 2026. Passos de migração:
  acme.example/docs/pagination

### Novo
- Visualizações salvas na caixa de entrada. Fixe um filtro uma vez e
  reutilize-o pela barra lateral.
- Webhooks agora podem ser limitados a um único projeto.

### Melhorado
- Endpoints de listagem respondem cerca de quatro vezes mais rápido
  em contas grandes.
- O job de exportação agora informa o progresso em vez de parecer
  travado.

### Corrigido
- Membros convidados não veem mais um painel vazio antes do
  primeiro login.
- Carimbos de data/hora nas exportações agora respeitam o fuso
  horário da conta.

O que vai em cada seção

Mudanças que quebram compatibilidade

A única seção com um prazo dentro dela. Diga o que para de funcionar, o que fazer no lugar, e a data em que para. Se você ainda não decidiu a data, não publique a seção ainda: uma mudança que quebra compatibilidade sem data é lida como urgente, e um fluxo de falsa urgência é como as pessoas aprendem a ignorar suas notas de versão.

Novo

Descreva o resultado, não o objeto que você construiu. O teste é se a linha ainda faz sentido para alguém que nunca viu seu código. "Visualizações salvas na caixa de entrada" passa. "Modelo SavedView e sua migração adicionados" não passa.

Melhorado

Quantifique onde você honestamente puder. "Mais rápido" vale quase nada e os leitores descontam isso; "cerca de quatro vezes mais rápido em contas grandes" vale a leitura e cria uma expectativa pela qual você pode ser cobrado. Se não puder medir, diga o que está melhor de um jeito que pode ser refutado.

Corrigido

Escreva o sintoma, não a causa. Os usuários pesquisam essas notas pela coisa que aconteceu com eles, então "membros convidados caíam em um painel vazio" é encontrável e "corrigida uma condição de corrida no cache de membros" não é.

Variantes

As quatro seções valem para a maioria dos lançamentos. Três casos pedem uma mudança:

• Lançamentos de apps móveis. As lojas de apps mostram um campo curto de novidades, então comece com uma frase que dá para ler na listagem da loja, depois link para as notas completas. A revisão da loja também pode segurar um build por dias, então date as notas pela data de lançamento, não pela data de merge.
• Lançamentos de API. Versione as notas do mesmo jeito que versiona a API, e coloque a janela de descontinuação nas próprias notas em vez de só na documentação. Um consumidor de API lê as notas exatamente para descobrir quanto tempo ainda tem.
• Ferramentas internas ou administrativas. Elimine a seção Melhorado e mescle com Corrigido. Usuários internos se importam se o fluxo de trabalho deles mudou, e uma seção Melhorado longa esconde isso.

Quatro regras que mantêm isso legível

1. Escreva para alguém que não conhece seu código. Sem nomes de arquivos, sem nomes de branches, sem IDs de tickets, sem nomes de serviços, sem codinomes internos.
2. Deixe de fora qualquer coisa sem efeito visível para o usuário. Atualizações de dependências, refactors, mudanças de CI e correções de digitação pertencem ao histórico de commits, não às notas de versão. A forma mais comum de notas de versão morrerem é enchendo com trabalho que ninguém fora da equipe consegue ver.
3. Uma entrada, uma mudança. Se uma linha precisa da palavra "e" duas vezes, provavelmente são duas entradas.
4. Publique em um ritmo que as pessoas possam contar, mesmo que o ritmo seja "sempre que lançamos". Notas que aparecem quatro vezes em uma semana e depois somem por dois meses são tratadas como ruído.

Formato de notas de versão: as partes, em ordem

O formato importa menos que a ordem. Qualquer estilo de título que você use, um leitor examinando notas de versão quer as mesmas quatro coisas na mesma sequência, e todo formato popular de notas de versão é uma variação disso.

1. Um título que diz o que mudou para o leitor, não o número da versão. A versão vai numa linha menor embaixo, com a data em formato ISO (2026-08-29) para que leia igual em qualquer local.
2. Mudanças que quebram compatibilidade e qualquer coisa com prazo, primeiro, mesmo que pequena. Se um leitor parar depois de um parágrafo, este é o parágrafo de que precisava.
3. O que é novo, um item por parágrafo, com o resultado na primeira frase e a ação necessária, incluindo "nenhuma ação necessária", declarada sempre.
4. Correções e melhorias, depois tudo o mais como uma lista de uma linha no final. Atualizações de dependências e mudanças internas permanecem, porque a única pessoa que procura por elas realmente precisa delas.

Em Markdown isso é um título H2, uma linha de versão e data em tom neutro, depois seções H3 para Quebras, Novo, Melhorado e Corrigido. Em um e-mail é a mesma ordem com o título como assunto. Em um widget de changelog é o título e o primeiro parágrafo, com o resto atrás de um link. O modelo acima é essa forma escrita por extenso.

Para a escrita em si, e não a forma, veja como escrever notas de versão que as pessoas realmente leem e boas práticas de notas de versão que valem a pena manter no blog.

Perguntas frequentes

Quanto tempo as notas de versão devem ter?

O tanto que as mudanças que afetam os usuários exigirem, e nem mais. Um lançamento com uma correção de bug leva duas linhas. Encher um lançamento pequeno para parecer substancial treina as pessoas a passarem por cima dos grandes.

Qual é a diferença entre notas de versão e um changelog?

Na prática os termos são usados como sinônimos. Onde as equipes os distinguem, notas de versão descrevem um único lançamento e são escritas para usuários, enquanto um changelog é a lista contínua de todos os lançamentos ao longo do tempo. Este modelo cobre um lançamento; um changelog é o que você tem ao empilhá-los do mais novo para o mais antigo.

Notas de versão devem ter um número de versão?

Só se seus usuários conseguem vê-lo. Números de versão são úteis para APIs, bibliotecas e software instalado, onde o leitor precisa saber em qual versão está. Para um app web continuamente implantado, a data é mais útil, porque é o que o usuário consegue comparar com a própria experiência.

Quem deveria escrevê-las?

Quem sabe o que mudou, o que geralmente significa o engenheiro que fez o merge, editado por quem é dono da voz. O modo de falha de entregá-las inteiramente a alguém fora do trabalho são notas que descrevem o ticket em vez da mudança.