Como gerar Changelog automaticamente através dos commits

Uma das maiores vantagens trazidas pela automação é o fato dela garantir um padrão de qualidade. Bom ou ruim, toda a construção feita pela automação seguirá a risca as mesmas especificações, resultando em um conjunto de produtos com as mesmíssimas características. Agora, o que aconteceria se a matéria prima fosse de baixa qualidade e o processo estivesse mal desenhado? É por conta disso que, antes de saber como gerar changelog automaticamente através dos commits, você precisa entender primeiro como fazer bons commits. Mas só isso não é o bastante.

O Changelog, como o próprio nome diz, armazena o histórico de modificações entre as versões do seu software. Mas para que ele seja organizado e faça sentido, é preciso que você tenha um bom plano de release. Que as suas demandas estejam bem organizadas em features, que exista um road map e você saiba aonde quer chegar com o desenvolvimento. Não dá pra falar de versionamento programando Go Horse. E se você está se perguntando se eu estou falando do SemVer, você tem toda razão!

Qual ferramenta eu uso pra gerar o changelog automaticamente?

Eu pesquisei algumas ferramentas que prometem gerar o changelog automaticamente através dos commits. No entanto, eu achei a maioria delas muito opiniosa em relação ao seu fluxo de delivery. Algumas já geravam o changelog, faziam merge na master e geravam a tag. Mais um pouco e elas estariam entregando café na minha casa. Se nós utilizamos o princípio da responsabilidade única no desenvolvimento do software, seria bom que também utilizássemos esse mesmo princípio em ferramentas, ou que pelo menos, o comportamento múltiplo seja configurável.

Foi então que eu encontrei o standard-version. Trata-se de um pacote node – e não se acanhe de misturar código javascript e C# – que lê os seus commits e gera um arquivo CHANGELOG.md. Ele cai como uma luva justamente porque ele permite que alguns dos passos sejam configuráveis. Isso nos concede liberdade para implementar a estratégia de release que desejarmos. Também existem outras configurações sobre a versão, quais commits entram ou não no changelog. Eu particularmente gostaria de ter a opção de criar um modelo de changelog, semelhante ao do auto-changelog. Mas essa feature ainda não está disponível no standard-version.

Como configurar o standard-version?

A primeira coisa é adicionar a dependência ao seu projeto:

npm i --save-dev standard-version

Depois, no package.json, você vai alterar o objeto scripts, adicionando a propriedade:

  "scripts": {

    ...
    "release": "standard-version"
  }

Apenas com essas configurações já seria possível gerar o CHANGELOG com o standard-version. Mas lembra que eu disse que ele é configurável? Para configurá-lo, você vai criar o arquivo .versionrc.json (ou .versionrc ou .versionrc.js):

{
  "types": [
    { "type": "feat", "section": "Features" },
    { "type": "fix", "section": "Bug Fixes" },
    { "type": "chore", "hidden": true },
    { "type": "docs", "hidden": true },
    { "type": "style", "hidden": true },
    { "type": "refactor", "hidden": true },
    { "type": "perf", "hidden": true },
    { "type": "test", "hidden": true },
    { "type": "build", "hidden": true }
  ],
  "commitUrlFormat": "https://dev.azure.com/COMPANY/project/_git/repository_name/commit/{{hash}}",
  "compareUrlFormat": "https://dev.azure.com/COMPANY/project/_git/repository_name/branchCompare?baseVersion=GT{{previousTag}}&targetVersion=GT{{currentTag}}&_a=files"
}

No exemplo acima, estou especificando quais tipos de commit (lembra do commit semântico?) devem ser adicionados ou escondidos no CHANGELOG e qual seria o nome da seção em que eles são agrupados. No final, também configuro o formato das URL que serão utilizados para construir o link para os commits e também a URL de comparação com a tag anterior. O formato é do Azure DevOps, mas você obviamente pode colocar a URL que preferir.

Faltou apenas configurar as tarefas que o standard-version deverá executar, correto? No arquivo package.json, adicione uma nova propriedade no objeto raiz:

"standard-version": {
    "skip": {
      "tag": true
    }
  }

Com as opções bump, changelog, commit e tag, você pode especificar quais dessas ações você deseja que o standard-version não execute. Mas porque você iria querer isso?

CHANGELOG é mais do que um log

Em algum momento desse artigo você deve ter pensado que, dado esse requisito, seria muito simples apenas formatar a saída de um git log para um arquivo .md. E se todos esse fosse o trabalho para gerar um CHANGELOG, você teria razão. Acontece que não é.

Um bom CHANGELOG, mais do que apenas o histórico dos commits, deve também contar a história do software. Algum endpoint está sendo depreciado? Você retirou alguma funcionalidade? Foi encerrada alguma issue de segurança? Lembre-se que o CHANGELOG é uma documentação a ser lida por pessoas. Essas pessoas podem ser outras desenvolvedoras ou até mesmo o usuário final. A pura e simples extração de logs não acrescenta muito.

Então, ainda que a sua equipe esteja aplicando corretamente o commit semântico, pode ser que alguém errou alguma coisa em algum momento. Ou algum detalhe não ficou suficientemente evidente. Nesse caso, vale muito a pena você não permitir que a ferramenta faça todo o ciclo automaticamente. Você pode fazer uma revisão do changelog e submeter aos seus pares para aprovação, como quem pergunta: “Gente, foi isso mesmo que nós fizemos e estamos entregando nessa versão. Correto?

Eu recomendo que você visite este site para entender melhor como escrever um changelog que realmente agregue valor a sua entrega.

Concluindo…

Você já deve ter percebido que o lançamento de uma release pode ser um pouquinho mais complicado do que apenas despejar um executável pra download em algum lugar, ou ainda, fazer o rollout de uma versão. Deve existir uma etapa de comunicação. Todas as pessoas envolvidas no projeto precisam saber o que está sendo entregue. E não falo apenas do time de desenvolvimento (e aqui incluo SCRUM Masters, PO e etc). Esse “todas” inclui também as pessoas que estão utilizando o sistema. Você pode ganhar pontos no NPS quando alguém percebe que um bug foi corrigido ou que uma feature solicitada foi implementada. Comunicação é importante.

Mas existe um outro grupo de pessoas e coisas que precisam estar por dentro do que acontece no seu software. Esse grupo são “os outros times” e “os outros sistemas”. Como um sistema poderia saber qual versão do seu sistema utilizar? Como saber se ainda existe compatibilidade entre as versões? É o que nós veremos em breve.