Automatizando geração de changelogs em seus projetos NodeJS

Tiago Boeing
5 min readJan 3, 2020

- English version

Escrever relatórios de mudanças de uma aplicação (CHANGELOG) de forma manual é sempre um sacrifício, desde lembrar de documentar as alterações ao finalizar a tarefa, quanto manter organização de acordo com os padrões previamente estabelecidos para o projeto ou pela organização, as informações podem acabar se misturando e gerar inconsistências com muita facilidade.

Alguns meses comecei a trabalhar em diversos projetos paralelos e busquei uma forma de automatizar e padronizar este processo de documentar os épicos no fluxo de desenvolvimento da aplicação, foi quando encontrei a dependência auto-changelog que atendeu às necessidades.

A configuração é recomendada para novos projetos ou que estejam seguindo uma padronização das mensagens de commit desde o início. Desde a validação através de hooks do Git ou por parte dos desenvolvedores.

Repositório com kit inicial e todas as configurações realizadas neste artigo: https://github.com/tiagoboeing/auto-changelog-starter-kit

Qual será o resultado?

Exemplo de changelog gerado para uma versão ainda não lançada (unreleased)
Exemplo de um changelog gerado — aplicação de autenticação — em uma versão ainda não gerada (unreleased) — Integração com ClickUp.

No exemplo da imagem é possível identificar links e o hash do commit:

  • 1b1c76: Tarefa relacionada no ClickUp e link para a mesma
  • Endpoint para autenticação, emissão de token e validação de headers: Mensagem de commit
  • (2dad914): Hash do commit no Git

Tenha em mente que no exemplo do artigo as releases (versões geradas) estarão no padrão SEMVER, isto é:

  • 1.0.0; 1.1.0; 2.0.0; 2.0.1 …….… 33.22.1

Ao trabalho

Instale em seu projeto a dependência auto-changelog:

npm install auto-changelog --save-dev# ouyarn add auto-changelog --dev

Se deseja apenas realizar testes, instale globalmente utilizando:

npm install -g auto-changelog

Caso não tenha optado por instalar globalmente, no package.json do seu projeto defina os scripts para rodar o auto-changelog :

scripts: {
"changelog": "auto-changelog --template changelog-template.hbs -p -u --commit-limit false",
"changelog-debug": "auto-changelog --template changelog-template.hbs -p --template json --output changelog-data.json"
}
...

O único script realmente essencial é o changelog , o changelog-debug é opcional, embora seja extremamente interessante para você ajustar de acordo com as necessidades do seu projeto e conferir a forma com que o changelog será montado.

Entenda o comando de geração:

auto-changelog --template changelog-template.hbs -p -u --commit-limit false
  • auto-changelog — dispara dependência para realizar o trabalho
  • --template changelog-template.hbs— informa para utilizar um arquivo que define os padrões para gerar o changelog
  • -p — a versão SEMVER a ser utilizada será a que consta no package.json na propriedade version
  • -u — define que mesmo as versões ainda não geradas devem ser enviadas ao changelog (ideal para acompanhamento do que está a ser liberado)
  • --commit-limit false — remove limite de commits no arquivo de changelog, por padrão apenas 3 commits serão relacionados

Por padrão o nome do arquivo a ser gerado será CHANGELOG.md .

É possível customizar o nome do arquivo com: -o ou --output HISTORY.md

Integrando com ClickUp, Jira, etc e restringindo branches

Mesmo que não vá integrar com ClickUp ou afins, esta etapa é primordial para o correto funcionamento. No cenário de não integrar as propriedades replaceText e issueUrl podem ser removidas ou apenas inicializadas como: um objeto vazio {} e string vazia "" , respectivamente.

No seu package.json crie uma nova propriedade incluindo:

"auto-changelog": {
"commitLimit": false,
"unreleased": true,
"issueUrl": "https://app.clickup.com/t/{id}",
"replaceText": {
"[Ff]eature:": "",
"[Ff]ix:": "",
"[Bb]reak:": "",
"^ #(.{6})\\s": "[$1](https://app.clickup.com/t/$1) - "
},
"includeBranch": [
"develop",
"master"
]
}
  • issueUrl — define a estrutura do link da tarefa, se existir
  • replaceText — remove as palavras que serão utilizada na mensagem de commit, no nosso caso (fix, feature ou break)
  • “^ #(.{ … — pega o número da tarefa e transforma em um link markdown. Exemplo: #1b1d0g se tornará * [1b1c76](https://app.clickup.com/t/1b1c76)
  • includeBranch — considera as mensagens de commits apenas nos branches: develop e master. (Interessante no caso em que a mensagem da MR/PR será padronizada e evita com que diversos registros indesejados sejam incluídos)

Como fallback commitLimit e unreleased são definidos aqui, embora o CLI esteja os sobrescrevendo, se considerar interessante remova-os.

Prefere Jira?

Sem problemas, eis aqui o arquivo:

"auto-changelog": {
"commitLimit": false,
"unreleased": true,
"issueUrl": "http://jira.user.com.br/browse/{id}",
"replaceText": {
"[Ff]eature:": "",
"[Ff]ix:": "",
"[Bb]reak:": "",
"([A-Z]+-\\d+)": "[$1](http://jira.user.com.br/browse/$1) - "
},
"includeBranch": [
"develop",
"master"
]
}

Definindo padrões para o changelog

Na raiz da aplicação (ao lado do seu package.json ) crie um arquivo com o nome definido na propriedade —-template , caso apenas tenha copiado o nome do arquivo será changelog-template.hbs

Dentro do arquivo cole o seguinte conteúdo:

Entendendo a template:

As variáveis do auto-changelog devem ser utilizadas com interpolação: {{variavel}}

  • {{#each releases}} : itera cada versão/release, no nosso caso incluímos as que ainda não foram geradas
  • # {{title}} : criamos um cabeçalho markdown de nível 1 que conterá o nome da versão 1.0.0 . Logo abaixo adicionamos a data da versão em padrão ISO 2020–01–03 .
  • Criamos três seções no changelog, uma para novas funcionalidades (features), correções (bugfix, hotfix, etc) e apenas quebra de compatibilidade.
  • {{#commit-list}} : itera a lista de commits buscando por mensagens que correspondam ao Regex da propriedade message e excluímos as que estão na propriedade exclude .

Como utilizar?

Caso não tenha alterado a template do artigo, para “documentar” suas alterações, como visto teremos três seções possíveis:

  • feature: (novas funcionalidades)
  • fix: (correções)
  • break: (quebra de compatibilidade)

Em sua mensagem de commit inclua um dos códigos das seções. Simulando um commit com tarefa relacionada no Clickup, teremos a seguinte sintaxe:

feature: #1b1d0g Adiciona nova dependência

Não possui tarefa no ClickUp, Jira, etc?

feature: Adiciona nova dependência

Gerando changelog

Finalizamos! Basta gerar o changelog rodando:

npm run changelog# ouyarn changelog

Se preferir verificar em um arquivo .json o que será gerado, rode npm run changelog-debug e na raiz do seu projeto, logo ao lado do package.json será criado um arquivo chamado changelog-data.json . Este foi o motivo de criarmos a tag changelog-debug nos scripts da aplicação. 😉

O arquivo gerado será o CHANGELOG.md. Cuidado que caso já exista um o mesmo será sobrescrito.

Fique livre para automatizar esta etapa no CI.

Documentação relacionada

--

--

Tiago Boeing

🇧🇷 Software engineering specialist | AWS Community Builder | ⌨ Works at Sulamérica | @tiagoboeing