Changelog vs release notes: qual é a diferença?

Um changelog é um registro contínuo e cumulativo de tudo que mudou, escrito para alguém que está procurando algo. Release notes são uma mensagem selecionada sobre uma release, escrita para alguém que decide se isso importa para ele. A diferença é o público, não a formatação, e a maioria das equipes precisa de ambos: um como referência, outro como anúncio, derivados das mesmas entradas.

A maioria das equipes acaba com um deles por acidente e o outro por solicitação. Você começa com um changelog porque uma desenvolvedora quer um registro do que foi lançado. Meses depois alguém do suporte pergunta por que os clientes não sabiam sobre um recurso que está no ar desde abril, e agora vocês precisam de release notes.

Changelog vs release notes, lado a lado

O que é um changelog?

Um changelog é um registro cronológico, quase completo, do que mudou, mais recente primeiro, com cada entrada tipada (added, changed, deprecated, removed, fixed, security) e datada. Seu leitor já decidiu que se importa. Ele está procurando algo: quando um comportamento mudou, se um bug foi corrigido, qual versão introduziu uma flag. Completude é todo o valor, por isso a convenção Keep a Changelog gasta a maior parte de sua única página em estrutura e quase nada em prosa.

O que são release notes?

Release notes são uma mensagem seletiva, escrita em prosa, sobre uma release. Seu leitor ainda não decidiu nada. Ele está decidindo se esta release importa para ele, e se precisa fazer algo a respeito. Seleção é todo o valor: uma release note que lista tudo é um changelog com parágrafos, e falha o leitor da mesma forma que um changelog que pula coisas falha o seu. Como escrever release notes trata da seleção e da formulação.

Você precisa de um changelog e de release notes?

Vocês precisam de ambos assim que os dois públicos quiserem coisas diferentes; até lá, um único artefato fazendo os dois trabalhos é correto. Equipes pequenas publicam uma única página /changelog com um parágrafo curto no topo de cada entrada, e por um tempo isso serve igualmente bem a uma desenvolvedora procurando uma correção e a uma cliente passando os olhos por novidades. Dividir cedo demais dá a vocês duas coisas para manter e uma delas vai apodrecer.

A divisão vale a pena quando isso começa a acontecer:

• As entradas de changelog de vocês cresceram parágrafos explicativos que desenvolvedores pulam.
• Ou o oposto: os anúncios de release de vocês começaram a listar atualizações de dependências.
• O suporte está copiando entradas para e-mails e reescrevendo-as no caminho.
• Alguém pede “só as mudanças que quebram algo” e vocês não conseguem filtrar por isso.

Esse último é o verdadeiro sinal. Se ninguém consegue responder “o que mudou que me afeta” sem ler tudo, vocês têm um artefato fazendo dois trabalhos mal.

Uma fonte, duas visões

O erro é tratá-los como dois documentos. São duas visões sobre o mesmo conjunto de mudanças.

Escrevam o changelog ao longo do caminho, uma entrada por mudança significativa, cada uma marcada com o que é: fixed, added, changed, removed, deprecated, security. Mantenham as entradas curtas o suficiente para que escrever uma não seja uma decisão. Depois, no momento da release, release notes são uma seleção e uma reescrita: peguem as entradas que importam a uma pessoa, agrupem-nas pelo que permitem que alguém faça, e coloquem o motivo no topo.

Isso tem uma consequência prática. Se o changelog é a fonte, ele precisa ser dados estruturados, não uma página mantida manualmente. Uma entrada precisa de um tipo, uma data, uma versão, e uma forma de dizer para quem é. Assim que tiver isso, a página pública, o widget in-app e o feed RSS ou JSON são três renderizações de uma coisa só, e ninguém reescreve nada no caminho até um cliente. Um e-mail de release notes pode citar a mesma entrada, a partir de qualquer ferramenta que envie os e-mails de vocês. Automação de changelog trata de qual dessas etapas uma máquina deveria possuir. Esse é todo o argumento para tratar um changelog como um feed em vez de uma página. É também, com total transparência, o que construímos, então leiam isso como um interesse em vez de uma pesquisa imparcial.

Se você só tiver tempo para um

Escrevam o changelog. É mais barato por entrada, é útil no dia em que você o escreve, e release notes podem ser derivadas dele depois. O contrário não é verdade: vocês não conseguem reconstruir um ano de mudanças a partir de doze e-mails de anúncio, e as pessoas vão pedir isso a vocês.

Mantenham-no em um formato fixo para que a derivação continue possível. Nossa página exemplos de changelog reúne entradas de equipes que fazem isso bem, e o template de release notes é a forma que usamos ao transformar um conjunto de entradas em algo que vale a pena enviar.

Uma nota sobre nomenclatura

Nada disso é padronizado, e vocês vão encontrar “release notes” usado para uma lista contínua e “changelog” usado para um anúncio trimestral. Discutir sobre as palavras não vale a pena. Decidam qual dos dois trabalhos cada um dos artefatos de vocês está fazendo, nomeiem-no como sua equipe já chama, e garantam que nenhum dos dois esteja silenciosamente fazendo os dois.

Em que superfície o resultado acaba é uma decisão separada, coberta em como construir uma página de changelog.

FAQ

Um changelog é o mesmo que release notes? Não. Um changelog é o registro completo, lido por quem procura algo; release notes são o anúncio selecionado, lido por quem decide se importa. A mesma mudança aparece em ambos, formulada diferentemente para cada leitor.

Release notes podem ser geradas a partir de um changelog? Sim, e essa é a direção certa. Selecione as entradas que importariam a uma pessoa, agrupe-as por resultado, reescreva o título. O contrário, reconstruir um changelog a partir de anúncios, perde tudo que os anúncios deixaram de fora.

Onde um changelog deveria viver? Em algum lugar permanente e linkável que o leitor possa alcançar sem um repositório: uma página /changelog, um site de docs, ou um feed que é renderizado em vários lugares. Um CHANGELOG.md sozinho alcança colaboradores, não clientes.

Um changelog deveria incluir mudanças internas? Sim, no final, uma linha cada. O changelog é o registro completo. As release notes também podem mantê-las, em uma seção final curta, desde que as mudanças que o leitor vai notar venham primeiro.

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: Exemplos de changelog, Modelo de notas de versão