Commit semântico: um guia completo para otimizar o seu projeto

Antes de iniciar o assunto principal deste artigo, é interessante esclarecer alguns conceitos que são importantes para a total compreensão do conteúdo apresentado nas linhas abaixo.

O que é commit?

O commit, de maneira resumida, é o registro das alterações de um código em um determinado momento. Quando você está desenvolvendo um projeto, é interessante que você crie novas versões dos arquivos ao invés de alterar os materiais originais e, com o commit, você adiciona essas mudanças aos repositórios, criando históricos lógicos do desenvolvimento.

Dentro deste contexto, vale referenciar uma frase do glossário do Git, uma das principais plataformas de versionamento de código do mundo: “the entire history of a project is represented as a set of interrelated commits”, ou seja, todo o histórico de um projeto é representado por um conjunto de commits interrelacionados.

No GIT, você deve inserir os seguintes comandos no terminal para fazer um commit:

O que é semântica?

De acordo com o dicionário Michaelis, semântica é o “ramo da linguística que estuda a significação das palavras e suas mudanças de sentido ao longo do tempo, bem como a representação do sentido dos enunciados”.

Na área de tecnologia, semântica é complementar à sintaxe. Enquanto a sintaxe se refere à estrutura de um programa, semântica está ligada ao significado, à interpretação do código.

O que é commit semântico?

Com base nos dois últimos conceitos, podemos dizer que commit semântico é uma boa prática para padronizar os commits de um projeto, facilitando a consulta e organização do próprio desenvolvedor e dos demais profissionais que necessitarão atuar no projeto. Os commits semânticos contribuem para a criação de um histórico lógico que possibilita a compreensão das alterações realizadas na visualização do repositório.

O projeto Conventional Commits, dedicado à criação de um modelo de padronização de commits, inspirado nas diretrizes do Angular Commit Messages Convention, descreve como: “a specification for adding human and machine readable meaning to commit messages”, ou seja, uma especificação para adicionar significados legíveis para humanos e máquinas em mensagens de commit.

Estrutura e tipos

O commit semântico pode ser estruturado das seguintes formas:

Para agilizar a rotina, o modelo pode ser seguido sem a utilização dos opcionais ou fazendo pequenas alterações na estrutura de acordo com as premissas da empresa ou do time de desenvolvimento.

• Tipo: especifica a atividade que foi realizada.
• Escopo: parte do código que sofreu a alteração.
• Descrição: o que foi feito no commit.
• Corpo: detalhes sobre o que foi feito no commit.
• Rodapé: informa issue, id ou task utilizada na alteração do código commitado.
  

Abaixo, confira alguns dos principais tipos que podem ser incorporados na rotina.

Valores aceitos de acordo com o Karma Guidelines:

• fix: solução de um problema.
• feat: inclui um novo recurso na base.
• test: adiciona/refatora testes sem alteração em produção.
• refactor: refatora código em produção.
• docs: altera documentações.
• style: altera formatação sem alteração em produção.
• chore: atualiza tarefas sem alteração em produção.
  

Outros tipos que podem ser utilizados também são:

• ci: altera arquivos e scripts de configuração de CI.
• build: altera o sistema de compilação ou dependências externas.
• perf: melhora o desempenho.
• improvement: adiciona melhorias na implementação atual sem adicionar novo recurso ou corrigir problema.
• env: modifica arquivos de configuração.

É previsto que, ao adicionar alterações no código que eventualmente podem afetar o funcionamento do código, você deve inserir no body a tag BREAKING CHANGE.

Exemplos de commits semânticos com o modelo adaptado:

docs(readme): remove incorrect tag from api document

fix(containers): adjust argument of profile function

Especificações

Existem algumas especificações que são recomendadas pelos guidelines, tais como o Karma Guidelines:

• A mensagem deve conter menos de 150 caracteres no total; deve-se utilizar sempre o modo imperativo;
• A primeira linha não pode conter mais do que 70 caracteres; a segunda linha será sempre vazia;
• As demais linhas devem conter até 80 caracteres;
• O tipo e o escopo devem ser sempre em caixa baixa;
• O escopo pode ser vazio em casos que os parênteses são omitidos.
  

Ferramentas para auxiliar na criação das mensagens

Apesar de existir uma série de especificações para auxiliar na criação dos commits, existem algumas ferramentas que podem ser grandes parceiras na escrita das mensagens.

Commitizen

A biblioteca facilita e otimiza o processo de criação de commits com base no Conventional Commits. Com ela, é possível criar scripts que guiarão na criação das mensagens.

Commitlint

A ferramenta verifica se a mensagem escrita está dentro dos padrões definidos, que podem ser os já existentes ou totalmente personalizados. Caso o commit não siga as regras, a biblioteca mostrará um erro ao usuário.

Husky

Com o Husky, podemos definir um gatilho para que outra plataforma execute a verificação do commit, tal qual o Commitlint.

Por que aplicar no seu projeto?

Aplicar a padronização dos commits nos seus projetos contribuirá com a organização da equipe e compreensão do código por parte de novos desenvolvedores. A criação de um histórico do que foi desenvolvido otimiza o trabalho e possibilita recuperar trechos em casos de alterações indesejadas ou incorretas no código fonte.

Imagine você trabalhando em um projeto colaborativo, de código aberto. Se todos os envolvidos na construção do código utilizassem a premissa do commit semântico, provavelmente os repositórios seriam mais organizados e mais desenvolvedores se interessariam em participar do projeto, já que compreenderiam melhor o que está sendo feito naquele momento.

Além disso, há formas de automatizar o versionamento do seu código com uma ferramenta chamada Semantic Release. Vamos explicar um pouco mais sobre isto e sobre como ela funciona logo abaixo, mas, apenas para conectar ao nosso assunto principal, para que o Semantic Release seja efetivo, ele necessita que seu projeto conte com um histórico de commits descritivos e muito explicativos.

Releases

Releases são versões de uma aplicação. Para exemplificar esse conceito, podemos usar como exemplo o Angular, que já lançou uma série de versões do framework e hoje está na 15.

Nos repositórios, você pode criar releases com notas explicativas, os release notes, menções aos desenvolvedores do projeto, links e outros arquivos e informações relevantes da versão publicada.

Semantic Release

O Semantic Release é uma ferramenta de automação de fluxo de trabalho para lançamento de novas versões de uma aplicação e utiliza os commits para determinar qual é a versão, gerar changelog e publicar as atualizações. Por regra, o Semantic Release utiliza a padronização do Angular Commit Messages Convention, que também é base para o projeto Conventional Commits.

Nesse artigo, você conferiu um guia completo sobre commits semânticos. Aplique em seus projetos e aumente a produtividade de toda a equipe.

Sucesso!

Referências

• Git - gitglossary Documentation
• angular/CONTRIBUTING.md at 22b96b96902e1a42ee8c5e807720424abad3082a · angular/angular
• Understanding Semantic Commit Messages Using Git and Angular K arma - Git Commit Msg
• Semantic Commit Messages
• https://www.conventionalcommits.org/en/v1.0.0