Exemplos de changelog

1. Um lançamento SaaS rotineiro

O caso comum: um punhado de mudanças visíveis ao usuário, sem migração, sem drama. É curto porque o lançamento foi pequeno, e resistir ao impulso de encher é a maior parte da habilidade.

## 20 de agosto de 2026

### Novo
- Visualizações salvas na caixa de entrada. Fixe um filtro uma vez e
  reutilize-o pela barra lateral.

### Melhorado
- O job de exportação agora informa o progresso em vez de parecer
  travado em contas grandes.

### Corrigido
- Membros convidados não veem mais um painel vazio antes do
  primeiro login.

2. Um lançamento de API com uma descontinuação

O leitor de um changelog de API procura uma coisa: se sua integração está prestes a quebrar, e quanto tempo ainda tem. Coloque isso no topo e dê uma data.

## Acme API 4.2 - 20 de agosto de 2026

### 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
- Webhooks podem ser limitados a um único projeto.

### Melhorado
- Endpoints de listagem respondem cerca de quatro vezes mais rápido
  em contas com mais de 10.000 registros.

3. Um lançamento mobile

As lojas de apps mostram um campo de novidades truncado, e a revisão pode segurar um build por dias. Os dois fatos moldam a entrada.

## iOS 3.4.0 - 20 de agosto de 2026

Modo offline. Abra, leia e redija sem conexão;
tudo sincroniza quando você voltar a ficar online.

### Também neste lançamento
- Abertura mais rápida em dispositivos mais antigos.
- Corrigido um travamento ao abrir um link compartilhado do Mail.

4. Uma correção de segurança

A única entrada em que dizer menos é o correto. Os usuários precisam saber que devem atualizar; mais ninguém precisa de uma descrição precisa o bastante para atacar a versão que ainda não atualizaram.

## 20 de agosto de 2026

### Segurança
- Reforçamos a validação dos tokens de sessão. Contas em
  instalações autogerenciadas devem atualizar para 4.2.1 ou
  posterior. Reportado com responsabilidade; sem evidência de
  exploração. Detalhes: acme.example/security/2026-08

5. Como fica uma entrada ruim

Toda linha aqui é real na forma, e toda linha é um erro:

## v2.3.7

- PR #482 mesclado de feature/inbox-refactor
- lodash atualizado de 4.17.20 para 4.17.21
- Corrigida condição de corrida em MembershipCache.resolve()
- Várias correções de bugs e melhorias
- Modelo SavedView refatorado (obrigado, Dave!)

O que os bons têm em comum

• Descrevem um resultado, não uma implementação. Um leitor que nunca viu o código ainda consegue saber se a entrada o afeta.
• Deixam coisas de fora. Atualizações de dependências, refactors, mudanças de CI e renomeações internas estão ausentes, e essa ausência é o que mantém o resto legível.
• Colocam a coisa custosa primeiro. Se algo quebra, é o primeiro título, com uma data.
• São datadas de um jeito que o leitor pode usar: um número de versão onde os usuários conseguem ver versões, uma data onde não conseguem.
• São entediantes de propósito. Sem pontos de exclamação, sem adjetivos de marketing, sem "estamos animados para anunciar". As pessoas que leem um changelog estão procurando informação e vão se incomodar com qualquer coisa no caminho.

Perguntas frequentes

Que formato um changelog deve usar?

keepachangelog.com é o mais próximo de um padrão e os nomes de suas seções (Added, Changed, Deprecated, Removed, Fixed, Security) são amplamente reconhecidos. Importa muito menos que a redação dentro das seções. Um formato consistente com entradas vagas é pior que um formato solto com entradas específicas.

Com que frequência devemos publicar?

No ritmo que combinar com seus lançamentos, e de forma consistente. Publicar por lançamento é a regra mais simples. Agrupar um mês de lançamentos em um único post torna cada mudança individual mais difícil de encontrar depois, que é quando a maioria das pessoas realmente lê um changelog.

O changelog deve ficar no nosso site ou em uma página de terceiros?

No seu site, se possível, porque é ali que o tráfego e o valor de busca se acumulam, e porque um changelog no domínio de outra pessoa está a um link de distância do seu produto em vez de fazer parte dele. É esse o caso para servi-lo como um feed que você mesmo renderiza em vez de uma página hospedada para a qual você aponta um link.

Os usuários realmente leem changelogs?

Uma pequena fração lê regularmente e uma fração muito maior os pesquisa no momento em que algo muda debaixo deles. Esse segundo grupo é o motivo para escrever o sintoma em vez da causa: estão pesquisando o que aconteceu com eles, com as próprias palavras.

Leitura adicional: changelog vs. notas de versão, e Keep a Changelog, de fato implementado.