Commits semânticos no uso de Git e outros VCS (sistemas de versionamento de código), são a melhor forma de documentação de execução de implementação, por conferir contexto à gestão de mudanças.

Escrever mensagens de commits nada claras, como task done ou bug fixed não auxiliam na manutenção de código e no histórico evolutivo do sistema.

Analise o histórico de mensagens de commit a seguir:

commit e71fcf2022b6135e18777bdc58c2ac3180202ec7
Author: mazerdev
Date: Tue Apr 24 01:25:48 2021 +1000
Extrair informações de pagamento

commit d1952883b05b685f2d22e4c41b4fbc4362fd6bd0
Author: mazerdev
Date: Mon Apr 23 22:16:50 2021 +1000
[WIP] integração

commit 74b8920d96e3e09d5cd958ffa369a0e3c86a6851
Author: mazerdev
Date: Mon Apr 23 21:09:11 2021 +1000
Gerar link para pagamento

commit b02255b25eed57c7595504c66233d5ee3024190c
Author: mazerdev
Date: Mon Apr 23 18:32:40 2021 +1000
[WIP] Pesquisa nos widgets

O pensamento de quem escreve os commits assim seriam: “Eu nunca vou me preocupar em utilizar o commit body”.

Quando você está trabalhando em uma empresa que ao criar um PR, fazer revisão de código não é comum, ninguém se preocupará em lhe pedir para escrever uma boa mensagem de commit.

Porém, isto muda quando você começa a trabalhar com equipes com uma boa cultura de engenharia, onde escrever uma mensagem de commit explícita e semântica, define a aceitação e qualidade de suas entregas.

Por onde começar?

A maioria das linguagens de programação tem convenções bem estabelecidas sobre o que constitui seu estilo idiomático, ou seja, nomenclatura, formatação e assim por diante.

Existem variações dessas convenções, mas a maioria dos desenvolvedores concorda que escolher uma e cumpri-la é muito melhor do que o caos que surge quando todos fazem suas próprias escolhas em código compartilhado.

É importante então entender que a abordagem de uma equipe para seu log de commit não deve ser diferente.

Para criar um histórico de revisão útil, as equipes devem primeiro concordar com uma convenção de mensagem de commit que estabelece pelo menos as três coisas:

  • Estilo: Sintaxe de marcação, quebra de margens, gramática, capitalização, pontuação. Remova essas coisas, elimine as conjecturas e torne tudo o mais simples possível. O resultado final será um registro notavelmente consistente que não é apenas um prazer de ler, mas que na verdade é lido regularmente.
  • Conteúdo: Que tipo de informação deve conter o corpo da mensagem de commit (se houver)? O que não deve conter?
  • Metadados: Como os IDs de rastreamento de issues e tasks, os ids de Pull e Merge Requests, etc. devem ser referenciados?

Felizmente, assim como para linguagens de programação, existem convenções bem estabelecidas sobre como uma mensagem Git commit deve ser escrita para ser idiomática.

Assim, há nada que você e sua equipe precisem reinventar. Basta seguir as sete regras abaixo e você estará no caminho certo para se comprometer (commiting 😀 ) como um profissional.

As sete regras para uma mensagem semântica de commit do Git

Somente saiba que: tudo isso foi dito antes.

  1. Separe o assunto do corpo com uma linha em branco
  2. Limite a linha de assunto a 50 caracteres
  3. Coloque a linha de assunto em maiúscula
  4. Não termine a linha de assunto com um ponto
  5. Use o humor imperativo na linha de assunto
  6. Envolva o corpo em 72 caracteres
  7. Use o corpo para explicar o quê e por quê vs. como

Conventional Commits para commits semânticos

A especificação definida pelo Conventional Commits é oferecer uma convenção simples para utilizar nas mensagens de commit.

Ela define um conjunto de regras para criar um histórico de commit explícito, o que facilita a criação de ferramentas automatizadas baseadas na especificação.

Esta convenção se alinha com o SemVer, descrevendo os recursos, correções e modificações que quebram a compatibilidade, tudo nas mensagens de commit.

A mensagem do commit deve ser estruturada da seguinte forma:

<tipo>[escopo opcional]: <descrição>

[corpo opcional]

[rodapé(s) opcional(is)]

Vamos entender o que cada bloco de informação significa e como deve ser preenchido.

A mensagem do commit contém os seguintes elementos estruturais, para comunicar a intenção ao utilizador da sua biblioteca:

  1. fix: um commit do tipo fix soluciona um problema na sua base de código (isso se correlaciona com PATCH do versionamento semântico).
  2. feat: um commit do tipo feat inclui um novo recurso na sua base de código (isso se correlaciona com MINOR do versionamento semântico).
  3. BREAKING CHANGE: um commit que contém no rodapé opcional o texto BREAKING CHANGE:, ou contém o símbolo ! depois do tipo/escopo, introduz uma modificação que quebra a compatibilidade da API (isso se correlaciona com MAJOR do versionamento semântico). Uma BREAKING CHANGE pode fazer parte de commits de qualquer tipo.
  4. Outros tipos adicionais são permitidos além de fix: e feat:, por exemplo @commitlint/config-conventional (baseado na Convenção do Angular) recomenda-se build:chore:ci:docs:style:refactor:perf:test:, entre outros.
  5. Outros rodapés diferentes de BREAKING CHANGE: <descrição> podem ser providos e seguem a convenção simular a git trailer format.

Observe que esses tipos adicionais não são exigidos pela especificação do Conventional Commits e não têm efeito implícito no versionamento semântico (a menos que incluam uma BREAKING CHANGE). Um escopo pode ser fornecido ao tipo do commit, para fornecer informações contextuais adicionais e está contido entre parênteses, por exemplo feat(parser): adiciona capacidade de interpretar arrays.

Referências

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *