3 ferramentas para tornar os commits do seu repositório mais profissionais

Demonstre profissionalismo e maturidade em seus repositórios obedecendo boas práticas na construção de mensagens de commit Um repositório de...

Eduardo Costa

View posts by Eduardo Costa
Desenvolvedor Java apaixonado por tecnologia. Gosta de ler, escrever e principalmente ajudar outros desenvolvedores a construir e implantar aplicações cloud-native que sejam seguras, escalaveis e resiliente para que possamos juntos crescer em nossas carreiras se divertindo tecnologias inovadoras.
Data de publicação: 30/04/2020

Demonstre profissionalismo e maturidade em seus repositórios obedecendo boas práticas na construção de mensagens de commit

Um repositório de gerenciamento de versão com um histórico organizado das mudanças realizadas e com boas mensagens de commit demonstra maturidade e profissionalismo. Esta organização se inicia com a escrita de mensagens de commit que demonstre de forma clara a intenção da mudança realizada e possua uma estrutura padronizada e seguida por todos do time.

Neste artigo veremos como estruturar as mensagens de commit do seu repositório, criando um padrão a ser seguido por todos os desenvolvedores do time. Faremos uso de  ferramentas que irão auxiliar a escrita dessas mensagens além de validar e garantir que as regras definidas sejam seguidas.

As práticas aqui demonstradas podem ser aplicadas em repositórios Git independente da linguagem de programação mantida nestes repositórios.

A arte de escrever boas mensagens de commit

Escrever boas mensagens de commit pode ser considerado uma arte, dominar esta arte leva tempo e exige prática. Ao realizar o commit do código, podemos considerá-lo como uma foto do seu trabalho. Se o código é a foto, a mensagem de commit que o descreve é a legenda.

É neste momento que o desenvolvedor se vê totalmente livre para descrever seu trabalho. Cada um o descreve da forma como preferir o que pode levar à diversos problemas. Sem uma padronização na estrutura das mensagens e a falta de regras básicas de escrita, estamos sujeitos a criar um repositório que não passa de um depósito de código. Não tiramos proveito dos recursos que uma ferramenta de gerenciamento de versão e futuramente quando for preciso procurar por algo no repositório, corremos o risco de perceber que todas aquelas mensagens pouco fazem sentido e tudo está uma verdadeira bagunça.

O artigo “How to Write a Git Commit Message” é um daqueles textos para se deixar no favoritos e revisitá-lo de tempos em tempos. Apesar de não haver um único padrão a ser seguido, podemos extrair algumas regras úteis:

  • Escreva o título de assunto de forma imperativa
  • Limite a quantidade de caracteres da linha do assunto
  • Não termine a linha de assunto com pontuação de período
  • Use o corpo da mensagem para explicar o Porquê ao invés de Como.
  • Limite a quantidade de caracteres para o corpo da mensagem e faça a quebra automática
  • Separe com uma linha em branco o título com o assunto do corpo da mensagem

Aplicar regras como estas sem uma ferramenta de auxílio é doloroso. Demonstraremos como suas mensagens de commit podem ser padronizadas, de forma que todas tenham os mesmos elementos e identifiquem de maneira correta qual o porquê daqueles trechos de código terem sido inseridos no repositório. Para isso utilizaremos três ferramenta desenvolvidas em javascript e que, apesar da sua linguagem de desenvolvimento javascript e o uso do Node.js, repositórios que armazenam código em qualquer linguagem (Java, Rudy, Go etc..) podem ser utilizados.

A ferramentas utilizadas são as seguintes:

Commitlint O commitlint  é uma ferramenta que através de seu conjunto de regras vai lhe ajudar a manter as mensagens dentro de alguma convenções, ela fará a validação das mensagens e indicará erros quando alguma das regras for violada.
Husky O Husky é uma ferramenta capaz de adicionar scripts (hooks) disparados antes (pre-commit) ou após (post-commit) seu “commit”. Ele será responsável por executar o commitlint antes que seu código seja “comitado” e assim evitar que uma mensagem mal construída seja enviada ao repositório git.
Commitizen O commitizen é uma ferramenta responsável por guiar o desenvolvedor durante a escrita de uma mensagem padronizada.  Uma sequência de opções será exibida para que seja preenchida qualquer campo obrigatório durante o “commit”.

Pre-requisitos

Como dito anteriormente, utilizaremos as ferramentas, Commitlint, Husky e Commitizen. Todas elas possuem como pré requisito o node.js e se integram com o gerenciamento de versão Git. Veremos como essas ferramentas podem ser instaladas em um computador com sistema operacional Linux.

Instalando o nvm e o node.js

Possuir o node.js instalado na estação de trabalho é um pré-requisito necessário à todos que irão realizar commits no repositório. Para isso precisamos realizar a instalação do nvm.

O nvm é um gerenciador de versões para o node.js. Nesse tutorial vamos utilizá-lo também para realizar a instalação do node.js. Se você utiliza o bash como shell, abra o terminal e digite o comando abaixo:

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash

Feche e abra novamente o terminal para verificar se a instalação foi realizada corretamente:

$ nvm --version
0.35.3

Se você utiliza o zsh como shell, será necessário alguns passos adicionais para concluir a instalação.Vamos agora instalar o node.js através do nvm. No momento da escrita deste artigo, a versão estável é a 12 (12.16.2)

$ nvm install node 12

Verifique se a instalação foi realizada corretamente:

$ node -v
V12.16.2

Verifique se o gerenciador de pacotes do node.js, o npm, também foi instalado corretamente:

$ npm --version
6.14.4

Configurando um repositório

O procedimento de configuração do repositório deve ser realizado uma única vez e preferivelmente antes do início do desenvolvimento pelo time. Após realizado, os desenvolvedores do time só precisarão realizar o comando nvm install na raiz do repositório antes de iniciar o trabalho e os procedimentos a seguir não precisam ser executados.

Depois de instalado o node.js vamos instalar as demais ferramentas dentro de um repositório Git já inicializado. Para se utilizar as ferramentas Commitlint, Husky e Commitizen na padronização de suas mensagens, é necessário configurar o repositório.

Se você utiliza um repositório remoto de gerenciamento de versão como GitHub ou Bitbucket, pode criar o repositório remotamente e realizar o clone para seu computador, caso prefira iniciar com um repositório local execute os comandos abaixo:

$ mkdir <nome-do-repositorio>
$ cd <nome-do-repositorio>
$ git init

Vamos alterar o arquivo .gitignore para ignorar a pasta node_modules, que é onde as ferramentas serão instaladas.

$ echo “node_modules/” >> .gitignore

Antes de executar a instalação propriamente dita, vamos criar o arquivo package.json que é responsável por armazenar as dependências e as configurações de todas as ferramentas que vamos utilizar. Execute o comando a seguir para criar um arquivo package.json no diretório corrente.

$ npm init -y

Vamos então instalar o Commitlint, responsável por verificar se sua mensagem de commit está dentro de um determinado padrão. Execute o comando a seguir e a ferramenta será instalada localmente dentro do diretório node_modules e uma nova entrada será adicionada no arquivo package.json.

$ npm install @commitlint/cli --save-dev

Em seguida vamos instalar o config-conventional, que é um conjunto de regras para as mensagens de commit. Execute o comando a seguir e a ferramenta será instalada localmente dentro do diretório node_modules e uma nova entrada será adicionada no arquivo package.json.

$ npm install @commitlint/config-conventional --save-dev

Nesse ponto é necessário informar ao Commitlint que ele deve utilizar as regras de validação presente no config-conventional. Para isso vamos criar o arquivo commitlint.config.js, utilizando o seguinte comando:

echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

A próxima ferramenta a ser instalada é o Husky, responsável por receber determinados eventos do gerenciador de versões Git e chamar o Commitlint, para validar a mensagem de “commit” que você acabou de digitar. Execute o seguinte comando:

$ npm install husky --save-dev

Agora precisamos configurar para quais eventos o Husky deverá atuar. Para isso adicione a seguinte seção ao seu arquivo package.json.

"husky": {
   "hooks": {
        "commit-msg": "commitlint -E HUSKY_GIT_PARAMS",
        "prepare-commit-msg": "exec < /dev/tty && git cz --hook || true"
        }
  },

De acordo com a documentação do Git, durante o evento “commit-msg” é possível formatar e/ou validar a mensagem de “commit”. Já o evento “prepare-commit-msg” nos permite executar algo antes do editor da mensagem de commit ser chamado. E é justamente nesse ponto que o Commitizen vai trabalhar, guiando o usuário na elaboração dessa mensagem.

Para instalar o Commitizen digite o seguinte comando:

$ npm install commitizen --save-dev

Temos também que configurá-lo para trabalhar com as regras de validação presente no config-conventional, executando o seguinte comando:

$ ./node_modules/.bin/commitizen init cz-conventional-changelog --save-dev --save-exact

Pronto, neste momento podemos testar se as configurações foram realizadas com sucesso.

Realizando commit em um repositório devidamente configurado

Adicione ao gerenciamento de versão todas as mudanças realizadas até o momento e dispare o commit:

$ git add .
$ git commit

Neste momento você será guiado para a construção da mensagem de “commit”. Também é uma boa prática não misturar em um único “commit” diversos tipos de mudança, de forma que os commits sejam atômicos e não deixem o repositório em estado de falha (quebrado).

Escolha o tipo de mudança que está sendo feita. Vamos escolher “feat” neste teste:

git commit
husky > prepare-commit-msg (node v12.16.2)
cz-cli@4.0.4, cz-conventional-changelog@3.1.0
? Select the type of change that you're committing: (Use arrow keys)
❯ feat:     A new feature 
  fix:      A bug fix 
  docs:     Documentation only changes 
  style:    Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) 
  refactor: A code change that neither fixes a bug nor adds a feature 
  perf:     A code change that improves performance 
  test:     Adding missing tests or correcting existing tests 
(Move up and down to reveal more choices)

Se seu repositório tiver vários módulos e você achar interessante informar em qual deles essas alterações foram realizadas, você pode especificá-lo aqui. Deixaremos em branco neste exemplo.

? Select the type of change that you're committing: feat:     A new feature
? What is the scope of this change (e.g. component or file name): (press enter to skip) 

Determine o título para sua mensagem, lembre-se da boa prática de colocar o título em modo imperativo.

? Select the type of change that you're committing: feat:     A new feature
? What is the scope of this change (e.g. component or file name): (press enter to skip) 
? Write a short, imperative tense description of the change (max 66 chars):
 (55) configure the repository for commit message conventions

Adicione uma descrição informando porquê a mudança foi necessária:

? Provide a longer description of the change: (press enter to skip)
 Specified a commit message convention for better track the changes in this repository through 
the use of the tools commitizen, commitlint and husky.

Informaremos que a mudança “comitada” não levou a quebra de compatibilidade com versões anteriores e também não está relacionada a um número de ticket aberto.

? Are there any breaking changes? (y/N) N
? Does this change affect any open issues? (y/N) N

Seu editor de texto será automaticamente aberto com uma prévia da mensagem que será “comitada”. Feche o editor e o “commit” será realizado com sucesso.


[master 47bb6b3] feat: configure the repository for commit message conventions
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 dummy.txt

ᐳ git log
commit 47bb6b3f6f1b37776ce365c7589345ffe3c4ecbd (HEAD -> master)
Author: Eduardo Costa 
Date:   Mon Apr 27 13:20:38 2020 -0300

    feat: configure the repository for commit message conventions
    
    Specified a commit message convention for better track the changes in this repository through the
    use of the tools commitizen, commitlint and husky.

Conclusão

As mensagens de “commit” são de suma importância para descrever o histórico de mudanças em um repositório. Encontrar uma forma adequada de escrevê-las não é uma tarefa fácil. O uso de técnicas como escrever o título de forma imperativa e o corpo do texto descrevendo o porquê da mudança no código nos ajuda a criar mensagens mais claras.

Padronizar as mensagens de “commit” do seu repositório demonstra maturidade e profissionalismo além de aumentar a confiabilidade na análise dos históricos de mudanças do software, auxiliando a reverter alterações e rastrear a causa raiz de defeitos.

O uso de ferramentas de automação como Commitlint, Commitizen e Husky garante que os padrões definidos não sejam quebrados e auxiliam os desenvolvedores na escrita de suas mensagens.

O que vem a seguir

Além dos benefícios já citados, a padronização das mensagens de “commit” é pré-requisito para automatizar o versionamento semântico, uma etapa importante da gerência de configuração de software. Isso é possível com o uso de ferramentas como  semantic release capaz de fazer o tagueamento e geração de changelogs de forma automática. Um bom tema para iniciar os estudos e um próximo artigo.

Artigo escrito pelos Dextranos Tulio Polachini e Edu Costa.

Eduardo Costa

View posts by Eduardo Costa
Desenvolvedor Java apaixonado por tecnologia. Gosta de ler, escrever e principalmente ajudar outros desenvolvedores a construir e implantar aplicações cloud-native que sejam seguras, escalaveis e resiliente para que possamos juntos crescer em nossas carreiras se divertindo tecnologias inovadoras.

Deixe uma resposta

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

2 + dezessete =

Posts relacionados

  1. Sobre a Dextra

    Somos especialistas em desenvolvimento de software sob medida para negócios digitais. Pioneiros na adoção de metodologias de gestão ágil, combinamos processos de design, UX, novas tecnologias e visão de negócio, desenvolvendo soluções que criam oportunidades para nossos clientes.

  2. Categorias

Scroll to top