Nomenclatura dos Commits

Este artigo descreve o padrão que adotamos para realizar a nomenclatura dos commits em nossos projetos.

Adotamos o padrão Conventional Commits, o qual inicia o commit com um prefixo como fix:, feat:, docs: para identificar o tipo da mudança.

Para mais informações, veja também o Guia de Commits do Angular que também usa o Conventional Commits.

Objetivos

Automatizar o versionamento de nossos projetos
Automatizar a geração do Changelog
Tornar o histórico de commits mais legível
Padronizar a comunicação entre a equipe

Automatizar o versionamento

É importante utilizar esse padrão pois os repositórios possuem (devem possuir) um Job de Versionamento na Pipeline de CI/CD. Esse job lê o nome dos commits e gera automaticamente a tag da versão do repositório no padrão de Versionamento Semântico.

Sintaxe dos Commits

Esta é a sintaxe dos commits que o Job de Versionamento está configurado para entender

<tipo>(<escopo opcional>): <descrição> [#<task redmine>]

<tipo>: Obrigatório. Refere-se ao tipo da alteração: se ele corrige um bug é um fix, se adiciona um feature, é um feat. Veja: Quais Tipos de Commits existem?
<escopo opcional>: Opcional. Descreve qual módulo do sistema foi alterado
<descrição>: Obrigatório. Descrição do o que o seu commit faz. Inicie sempre com verbos no presente do indicativo, ex.: corrige, altera, implementa, refatora, adiciona.
[#<task redmine>]: Opcional. Este é o ID da task do Redmine caso seu commit esteja relacionado. Ex: #39042

Quais Tipos de Commits existem?

Para o campo <tipo>, há as seguintes opções:

Tipo	Descrição	Versão	Roda a pipeline?
build	Mudanças que afetam o sistema de build (Dockerfile) ou dependências externas (requirements.txt)	Não altera	Sim
ci	Alterações na pipeline de CI/CD	Não altera	Sim
docs	Alterações na Documentação	Não altera	Não
feat	Um feature novo (alterações que adicionam funcionalidade)	Aumenta a Minor	Sim
fix	Uma correção de bug (alteração que corrige funcionalidade)	Aumenta o Patch	Sim
perf	Uma mudança no código que melhora a performance	Aumenta a Minor	Sim
refactor	Uma mudança de código que nem corrige bugs, nem adiciona features. Apenas Refatoração.	Não altera	Sim
test	Adição de novos testes ou correção de testes existentes	Não altera	Sim

Dica: Commits que começam docs: não disparam a pipeline. Caso não queria disparar a pipeline, pode usá-lo.

Exemplos

Veja como exemplo um histórico de commits de um projeto fictício para entender como que

Versão Atual	Nome do Commit	Nova Versão	Tipo de Alteração
1.2.4	fix: Corrige a formatação do parser markdown	1.2.5	Altera a versão de Patch
1.2.5	feat: Adiciona comando de pull para baixar novas páginas #37093	1.3.0	Altera a versão Minor
1.3.0	docs(comandos): Cria sessão explicando como usar o comando de pull	1.3.0	Versão se mantem igual

Como funciona?

Exemplo com este commit feito no TCE.Pipelines:

Encontrei um bug no Job de Versionamento.
Corrigi o erro em minha máquina, testei e estou pronto para commitar.
Como a alteração é uma correção de bug no módulo versioning, o commit se chamou: fix(versioning): corrige output do NEXT_VERSION.
Fiz push. No Gitlab, o Job de Versionamento leu o nome do commit entendeu que é um fix, e criou uma nova tag nesse commit. A tag anterior era 3.0.0, então ele aumentou para 3.0.1.
Após isso, o Job de Versionamento também gerou um changelog com as alterações.

Dica: Iniciar descrição do commit com o presente do indicativo

Por convenção, inicie a Descrição do commit com verbos no presente do indicativo. A descrição deve indicar o que o commit faz. Exemplos:

fix: corrige a formatação do parser markdown
feat: adiciona comando de pull para baixar novas páginas

A intenção é facilitar a leitura do histórico de commits, e dos changelogs.

Mais informações

Para informações completas da sintaxe dos commits e versionamento semântico: Versionamento Semântico e guia de commits do Angular.