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.
## 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.
O que funciona: cada linha é um resultado que um usuário poderia notar. Não há número de versão porque o produto é implantado continuamente, então a data é a única coisa que um leitor pode comparar com a própria experiência.
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 valornextCursorda 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.
## 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.
O que funciona: a descontinuação nomeia o parâmetro exato, o substituto, o modo de falha após o prazo, e a data. Um leitor pode decidir em uma linha se isso o afeta.
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.
## 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.
O que funciona: uma frase carrega o lançamento, porque é tudo que a listagem da loja vai mostrar. A data é a data de lançamento em vez da data de merge, então corresponde a quando os usuários realmente puderam obtê-lo.
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
## 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
O que funciona: diz ao leitor se deve agir sem nomear o endpoint, o parâmetro ou a técnica. O detalhe pertence a um comunicado de segurança em seu próprio calendário, depois que as pessoas tiveram tempo de atualizar.
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!)
## 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 dá errado: o número do pull request e o branch não significam nada fora do repositório. A atualização de dependência e o refactor não têm efeito visível para o usuário e não deveriam aparecer de forma alguma. A condição de corrida nomeia uma classe em vez do sintoma que o usuário viu. "Várias correções de bugs e melhorias" é a frase que as pessoas citam quando dizem que changelogs são inúteis. O agradecimento pertence ao commit.
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.
Changelogs que valem o estudo
As cinco entradas acima foram escritas para esta página. Estes são changelogs reais de produtos que muita gente usa todo dia, e de cada um vale copiar uma coisa específica.
- Linear abre cada post datado com o recurso de que trata, em uma ou duas frases sobre o que agora você consegue fazer, e leva à documentação para os detalhes.
- Stripe API registra cada mudança sob a versão nomeada da API em que saiu (Acacia, Basil, Clover e seguintes), para que uma integração fixada em uma versão leia exatamente o que mudou para ela.
- GitHub marca cada entrada como lançamento, melhoria ou descontinuação e indica a área do produto, para que cada leitor filtre o que usa. O changelog inteiro também é um feed RSS.
- Supabase marca cada entrada pelo tipo e divide as mais longas em o que há de novo e o que você ganha, com feed RSS e um link para copiar como Markdown.
- Tailwind CSS mantém um CHANGELOG.md no repositório no formato Keep a Changelog: uma seção Unreleased no topo, Added e Fixed em cada versão e um link para o pull request em cada linha.
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: o que é, com um exemplo de entrada; Changelog vs release notes: qual é a diferença?; Keep a Changelog, de fato implementado; Como depreciar uma API sem perder seus desenvolvedores e Release notes para apps mobile: o que o limite corta.
Entradas nesse formato, redigidas para você
O Changeloop lê o título e a descrição de cada pull request mesclado e escreve uma entrada como as acima, filtra atualizações de dependências e refactors, e segura para você editar antes de qualquer coisa ir ao ar. Grátis para um repositório, sem cartão.
Começar grátis