GREN + GitHub Actions: release notes de forma fácil e automatizada

Release notes é uma ferramenta de comunicação poderosa que, usada da maneira correta, abre um canal de engajamento exclusivo com seus usuários de forma a levar clareza sobre correções de bugs e novos recursos que eles tanto ansiavam. Mas, como integrar isso ao meu processo?

Se você está aqui, provavelmente já deve ter passado pela dolorosa tentativa de manter manualmente um release note. O processo de avaliar o que foi desenvolvido pelo time entre a release anterior e a atual é exaustiva, além de consumir um tempo que poderia ser investido em uma correção de bug.

Vou te mostrar uma combinação de ferramentas que vai te ajudar a ir pra um caminho automatizado e super fácil de ser configurado com: GREN e GitHub Actions.

GREN

O GREN (GitHub Release Notes) faz parte do repositório github-tools, e é um módulo Node criado para publicar release notes com base em commits entre as duas últimas tags.

Você pode escolher uma das seguintes fontes para preencher as informações sobre suas releases:

• issues (time based);
• issues (milestone based);
• commits;
• pull requests.

A documentação dele é bem completa, mas darei um exemplo aqui selecionando pull requests como base de informação.

Setup Local

A instalação é via npm, portanto execute o comando:

npm install github-release-notes -g

Além disso, ele precisa de um GitHub Token que pode ser exposto da seguinte maneira no seu terminal:

export GREN_GITHUB_TOKEN=your_token_here

Pronto! Agora basta criar um arquivo de configuração do GREN, onde você o informará algumas informações como: de onde que ele tem que tirar as informações, se você gostaria de agrupar as notas baseado em labels, o nome do arquivo que irá armazenar seu changelog etc.

Esse arquivo estará armazenado na raiz da pasta do seu projeto. Vou mostrar um exemplo de um, mas caso queira gerar manualmente, execute o seguinte comando e responda as informações solicitadas:

gren init

No final desse comando, um arquivo .grenrc.json (pode ser outro formato selecionado) estará na raiz do seu projeto. E, você poderia personalizá-lo da seguinte maneira:

• Data source: como citei anteriormente, pull requests foram escolhidos como fonte de informação.
• Changelog Filename: nome do arquivo de changelog.
• Ignore Tags With: esse campo é um array. Caso existam algumas tags que você não queira criar um release notes, você poderia especificar nesse campo um prefixo que elas possuem.
• Group By: pra mim, essa é uma das melhores features. Você pode agrupar suas issues/pull requests baseado em labels. Isso torna seu release notes muito mais legível e organizado, mas é necessário disciplina do time de associar as labels corretas.
• Template: além de poder agrupar, também é possível personalizar como gostaria a descrição de cada item. Nesse exemplo, estamos colocando o número do pull request com o link direto para abrí-lo, além de concatenar na frente o nome e as labels associadas a ele.

Esse é somente um exemplo para uma vasta utilização dos recursos desse arquivo. Na documentação é possível ler mais sobre eles, além de descobrir outras configurações.

OK, tenho meu arquivo do GREN configurado. Onde entra o GitHub Actions pra automatizar?

A melhor parte é agora, e vou te provar isso.

O GitHub Actions tem como propósito de te oferecer o poder de automatizar, personalizar e executar seus workflows de desenvolvimento de software diretamente no seu repositório. E vai ser exatamente isso que vamos fazer!

Se você já usa o GitHub Actions, você terá as seguintes pastas dentro da raiz do seu repositório:

.github/workflows/

Será nela que iremos criar um arquivo com o nome “gren.yml”. Caso você não tenha, basta criar. Nele colocaremos o conteúdo:

Quero destacar o passo: “Running changelog generator”, onde usamos três comandos:

• npm install github-release-notes -g: é a instalação do gren.
• gren release — override: esse comando cria novas notas para a última tag gerada. E, com o override, ele atualiza a descrição da release no repositório.
• gren changelog — override: esse passo é utilizado para extrair as releases do seu repositório (com as descrições atualizadas baseadas no repositório anterior) e extrair em um arquivo (lembra da configuração changelogFilename? Ela será utilizada aqui).

Os outros passos são para fazer o commit do seu arquivo de changelog atualizado.

Com a junção dessas duas ferramentas, sempre que você gerar uma tag nova de release, um gatilho ativará o pipeline criado e seus usuários terão informações detalhadas sobre o que foi implementado.

E aí, gostaram? Deixem nos comentários quais ferramentas vocês usam :D