guides

Um changelog é um ficheiro que lista as alterações notáveis feitas a um projeto, organizadas por versão. A sua função é responder a uma pergunta simples para quem usa o teu software ou depende dele: o que mudou entre a versão que eu tinha e a versão para a qual estou a passar. Como é escrito para pessoas e não para máquinas, um bom changelog realça o que de facto importa aos utilizadores e deixa de fora o ruído.

Convém esclarecer o que um changelog não é. Não é a saída em bruto do teu histórico de controlo de versões. Um git log lista cada commit, incluindo pequenos refactorings, correções de gralhas e commits de merge, pela ordem em que foram feitos e com a redação que o autor escolheu. Um changelog é um resumo curado e escrito por uma pessoa, que agrupa o trabalho relacionado, descarta os detalhes triviais e descreve cada alteração em função do seu efeito sobre quem a lê.

A convenção mais seguida para escrever um chama-se Keep a Changelog. Define um formato simples baseado em Markdown, normalmente num ficheiro chamado CHANGELOG.md na raiz do repositório. A ideia é que uma estrutura coerente e previsível torne o ficheiro fácil de percorrer, quer o leitor seja uma pessoa a navegar num alojamento de código, quer uma ferramenta que analisa as entradas.

O formato Keep a Changelog

Segundo essa convenção, cada versão publicada tem a sua própria secção, encabeçada pelo número de versão e a data em que foi publicada. Dentro de uma versão, as alterações são agrupadas sob um pequeno conjunto de cabeçalhos padrão para que os leitores encontrem depressa o que lhes interessa. Os grupos recomendados são Added para novas funcionalidades, Changed para alterações a comportamento existente, Deprecated para funcionalidades a caminho de desaparecer, Removed para as que já foram retiradas, Fixed para correções de bugs e Security para tudo o que se relaciona com vulnerabilidades.

As versões em si seguem normalmente o versionamento semântico, de modo que uma versão se lê MAIOR.MENOR.CORREÇÃO, como 2.4.1. Isto liga o changelog ao número de versão de forma útil: um leitor pode olhar para o salto de uma versão para a seguinte e formar uma expectativa. Uma alteração no número maior sinaliza que algo pode partir, enquanto um incremento de correção sugere apenas correções. O changelog explica depois, por palavras, o que está exatamente por trás desse número.

Ordem, datas e a secção Unreleased

Um changelog é normalmente mantido em ordem cronológica inversa, com a versão mais recente no topo, para que a informação mais relevante seja a primeira que o leitor vê. Cada entrada é datada, o que permite situar uma publicação no tempo e perceber quão recente é uma correção ou funcionalidade. Manter a ordem e as datas coerentes faz parte do que torna o ficheiro fiável num relance.

• Um changelog é um ficheiro que lista as alterações notáveis de cada versão, escrito para pessoas, não o git log em bruto.
• Keep a Changelog é a convenção comum, normalmente um CHANGELOG.md em Markdown na raiz do repositório.
• Grupos de alterações padrão: Added, Changed, Deprecated, Removed, Fixed e Security.
• As versões seguem normalmente o versionamento semântico (MAIOR.MENOR.CORREÇÃO), cada uma com a sua data de publicação.
• As entradas vão em ordem cronológica inversa, muitas vezes com uma secção Unreleased no topo.
• Podes gerar as entradas a partir dos commits (por exemplo Conventional Commits), mas um changelog escrito à mão é muitas vezes mais claro.

Uma adição comum e prática é uma secção Unreleased mesmo no topo. É aí que registas as alterações à medida que as fazes, antes de estarem ligadas a um número de versão. Quando estás pronto para publicar uma versão, renomeias essa secção com o novo número, dás-lhe uma data e inicias um novo bloco Unreleased. Este hábito faz com que o changelog seja escrito enquanto o trabalho está fresco, em vez de ser reconstruído de memória no último minuto.

Escrever boas entradas e gerá-las

Escrever boas entradas é sobretudo manter o leitor em mente. Cada alteração notável deveria ter a sua própria entrada, redigida para que alguém que não conhece os detalhes internos entenda mesmo assim o efeito. Vale a pena descrever o resultado para o utilizador em vez da mecânica do código, evitar o jargão interno e agrupar edições relacionadas numa única linha clara em vez de uma entrada por commit. As alterações triviais ou puramente internas podem ser omitidas por completo.

É possível gerar um changelog automaticamente a partir do teu histórico de commits, e muitas equipas fazem-no. Abordagens como Conventional Commits pedem que escrevas as mensagens de commit de forma estruturada, por exemplo prefixando-as com feat ou fix, para que uma ferramenta as possa ordenar nos grupos certos e montar um rascunho. Isto pode poupar tempo e impor coerência, mas o resultado tende a ler-se como uma lista de commits. Um changelog escrito ou pelo menos revisto à mão é muitas vezes mais claro, porque uma pessoa pode decidir o que vale a pena mencionar e formulá-lo para o público.

Em resumo

Em resumo, um changelog é um registo legível do que mudou em cada versão de um projeto, mantido para as pessoas que o usam. A convenção Keep a Changelog dá-lhe uma forma previsível, o versionamento semântico dá sentido aos seus números de versão, e um pouco de disciplina, como uma secção Unreleased e uma entrada por alteração notável, mantém-no exato. Quer seja escrito à mão, quer gerado a partir dos commits, o seu valor vem de ser claro, atual e centrado no que o leitor realmente precisa de saber.