Como e por quê fazer commits mais semânticos

Introdução

Opa galera, tudo tranquilo?

Hoje vamos falar de boas práticas para te tornar um(a) desenvolvedor(a) melhor, focando em uma ação que faz parte do dia-a-dia de todo desenvolvedor, o commit.

O que são commits mais semânticos?

Segundo a própria documentação do Conventional Commits, 'é 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. Esta convenção segue o SemVer, descrevendo os recursos, correções e modificações que quebram a compatibilidade nas mensagens de commit'.

A mensagem do commit deve ser estruturada da seguinte forma:

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

[corpo opcional]

[rodapé opcional]

Além dessa estrutura, o commit possui outros elementos estruturais.

Elementos estruturais

• fix - Commits do tipo fix indicam que seu trecho de código commitado está solucionando um problema (bug fix), (se relaciona com o PATCH do versionamento semântico).
• feat - Commits do tipo feat indicam que seu trecho de código está incuindo um novo recurso (se relaciona com o MINOR do versionamento semântico).
• docs - Commits do tipo docs indicam que houveram mudanças na documentação, como por exemplo no Readme do seu repositório. (Não inclui alterações em código).
• style - Commits do tipo style indicam que houveram alterações referentes a formatações de código, semicolons, trailing spaces, lint... (Não inclui alterações em código).
• refactor - Commits do tipo refactor referem-se a mudanças devido a refatorações que não alterem sua funcionalidade, como por exemplo, uma alteração no formato como é processada determinada parte da tela, mas que manteve a mesma funcionalidade, ou melhorias de performance devido a um code review.
• build - Commits do tipo build são utilizados quando são realizadas modificações em arquivos de build e dependências.
• test - Commits do tipo test são utilizados quando são realizadas alterações em testes, seja criando, alterando ou excluindo testes unitários. (Não inclui alterações em código)
• chore - Commits do tipo chore indicam atualizações de tarefas de build, configurações de administrador, pacotes... como por exemplo adicionar um pacote no gitignore. (Não inclui alterações em código)
• BREAKING CHANGE - Commits que possuem o texto BREAKING CHANGE no começo do corpo ou no rodapé, indicam que a modificação que está sendo realizada no commit, possui uma modificiação que quebra a compatibilidade da API, (se relaciona com o MAJOR do versionamento semântico).

Esqueleto

O corpo, o escopo e rodapé compôem o esqueleto de um commit semântico, e todos os três são opcionais.

O corpo é indicado para quando o detalhamento do seu commit for maior que 7 palavras.

Exemplo:

feat: adicionado a nova estrutura de pastas do frontend

- Foi realizada uma mudança em toda a estruturação de páginas do projeto frontend, pois agora iremos utilizar determinado modelo

Com o escopo iremos informar a parte do código que foi modificada. Pode ser o nome de um componente, uma determinada propriedade da API ou o nome da API, uma função...

Exemplo:

fix(ProdutoApi): retirando variável do path da API e ajustando loggers

- O path anterior tinha variáveis desnecessárias e não utilizadas

No rodapé geralmente são informados uma issue, id ou tasks de atividades, que foram utilizadas para realizar a alteração desse trecho de código commitado.

Exemplo de commit com escopo, corpo e rodapé:

fix: corrige pequenos erros de digitação no código

veja o ticket para detalhes sobre os erros de digitação corrigidos

originado da issue JD#12 

Por que utilizar?

• Criação automatizada de CHANGELOGs.
• Determinar automaticamente um aumento de versionamento semântico (com base nos tipos de commits).
• Comunicar a natureza das mudanças para colegas de equipe, o público e outras partes interessadas.
• Disparar processos de build e deploy.
• Facilitar a contribuição de outras pessoas em seus projetos, permitindo que eles explorem um histórico de commits mais estruturado.

Dúvidas recorrentes

Como devo lidar com mensagens de commit na fase inicial de desenvolvimento?

É recomendado que você proceda como se já tivesse lançado o produto. Normalmente alguém, mesmo que seja seus colegas desenvolvedores, está usando seu software. Eles vão querer saber o que foi corrigido, o que quebrou etc.

Os tipos no título das mensagens commit são maiúsculos ou minúsculos?

Qualquer opção pode ser usada, mas é melhor ser consistente. Eu particularmente prefiro commitar com letras minúsculas

O que eu faço se o commit estiver de acordo com mais de um dos tipos?

Volte e faça vários commits sempre que possível. Parte do benefício do Conventional Commits é a capacidade de nos levar a fazer commits e PRs mais organizados.

Isso não desencoraja o desenvolvimento rápido e a iteração rápida?

Desencoraja a movimentação rápida de forma desorganizada. Ele ajuda você a ser capaz de se mover rapidamente a longo prazo em vários projetos com vários colaboradores.

Ferramentas para Conventional Commits

• php-commitizen: uma ferramenta para criar mensagens de commit seguindo as especificações do Conventional Commits. Configurável e util para projetos PHP como dependência do composer ou “global” para projetos não-PHP.
• conform: uma ferramenta que pode ser usada para garantir “regras” em repositórios git, incluindo o Conventional Commits. standard-version: Geração automática de versões e gerenciamento de CHANGELOG, usando o novo botão de squash do GitHub e o workflow recomendado do Conventional Commits.

Conclusão

Por hoje é isso galera, espero que tenham curtido o tema e que a Coday possa ter ajudado vocês a evolouirem como desenvolvedores(as).

Se vocês tiverem quaisquer dúvidas relacionadas a commits mais semânticos, ou quiserem sugerir algum outro tema, deixem aqui nos comentários.