Automatizando geração de changelogs em seus projetos NodeJS

- 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 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
# ou
yarn 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
# ou
yarn 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

• auto-changelog no NPMJS: https://www.npmjs.com/package/auto-changelog
• Repositório oficial no GitHub: https://github.com/CookPete/auto-changelog