Conventional Commits: o que são e como usá-los

Você já se deparou com commits parecidos com esse da imagem acima, de diferentes formatos em projetos de software? Alguns são bem descritivos, outros nem tanto. Mas você já ouviu falar de Conventional Commits?

Conventional Commits é uma especificação de formato de mensagem de commit que padroniza a forma como as mensagens são escritas, com o objetivo de facilitar a compreensão do que foi alterado em um determinado commit. Com o uso de commits padronizados, é possível gerar changelogs automaticamente, além de manter o histórico de commits do projeto mais organizado e fácil de entender. Confira aqui informações detalhadas na documentação oficial.

O que são Conventional Commits?

Conventional Commits é uma especificação de formato de mensagem de commit que tem como objetivo padronizar a forma como as mensagens são escritas. A especificação define um conjunto de prefixos que indicam o tipo da alteração realizada no commit, seguido por um escopo (opcional), uma descrição curta e uma descrição mais detalhada (opcional).

Por exemplo, um commit com a mensagem “feat(blog): Adiciona post sobre Conventional Commits” indica que foi adicionada uma nova funcionalidade (feat) relacionada ao módulo de blog (blog), e a descrição curta e detalhada explicam o que foi adicionado.

Outros tipos de prefixos comuns incluem:

• fix: correção de bug
• docs: alteração na documentação
• style: formatação de código
• refactor: refatoração de código
• test: adição ou alteração de testes

A especificação também permite o uso de prefixos personalizados para atender às necessidades específicas do projeto.

Os commits padronizados podem ser usados em diferentes ferramentas de controle de versão, como Git, Mercurial e SVN. Além disso, existem várias ferramentas que suportam a geração automática de changelogs a partir dos commits padronizados, como o standard-version e o conventional-changelog.

Como usar Conventional Commits?

Para usar Conventional Commits em seu projeto, basta seguir as regras da especificação. O formato básico de uma mensagem de commit é o seguinte:

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

[descrição mais detalhada opcional]

Onde:

• <tipo> é um prefixo que indica o tipo da alteração realizada no commit (por exemplo, feat para uma nova funcionalidade ou fix para uma correção de bug).
• [escopo opcional] é um texto opcional que indica o escopo da alteração realizada no commit (por exemplo, o módulo do sistema em que a alteração foi feita).
• <descrição curta> é um texto curto que descreve a alteração realizada no commit.
• [descrição mais detalhada opcional] é um texto opcional que descreve com mais detalhes a alteração realizada no commit.

Por exemplo, se você quiser adicionar uma nova funcionalidade ao módulo de blog do seu projeto, poderia usar a seguinte mensagem de commit:

feat(blog): adiciona busca por tags nos posts
Adiciona funcionalidade que permite a busca por tags nos posts do blog

Se você quiser corrigir um bug na funcionalidade de login, poderia usar a seguinte mensagem de commit:

fix(login): corrige erro de autenticação com Facebook
Corrige erro que impedia a autenticação de usuários através do Facebook.

Lembre-se de que a descrição curta deve ser sucinta e descritiva o suficiente para que os outros desenvolvedores possam entender o que foi alterado no commit sem precisar ler a descrição detalhada. Já a descrição detalhada pode incluir informações adicionais, como o motivo da alteração, as dependências envolvidas e os testes realizados.

Só mais um exemplo:

refactor(Jira-Otao-123): refatora código de adição de produtos ao carrinho
Refatora código para melhorar a performance e reduzir a duplicação de código na função de adição de produtos ao carrinho.

Conclusão

Para usar Conventional Commits em seu projeto, basta seguir as regras da especificação e usar prefixos que indicam o tipo de alteração realizada no commit, seguido por um escopo (opcional), uma descrição curta e uma descrição mais detalhada (opcional). Lembre-se de que a descrição curta deve ser sucinta e descritiva o suficiente para que os outros desenvolvedores possam entender o que foi alterado no commit sem precisar ler a descrição detalhada.

Além disso, os commits padronizados podem ser usados em diferentes ferramentas de controle de versão, como Git, Mercurial e SVN. Existem também várias ferramentas que suportam a geração automática de changelogs a partir dos commits padronizados, como o standard-version e o conventional-changelog.

O uso de Conventional Commits pode ajudar a manter o histórico de commits do projeto mais organizado e fácil de entender, além de tornar mais fácil a comunicação entre os desenvolvedores sobre as alterações realizadas no código. Experimente implementar Conventional Commits em seu projeto e veja como pode ser útil.

Em uma próxima postagem, vou te mostrar uma ferramenta para PHP (sim, porque aqui amamos PHP e é sobre isso, haha, até mais!

Este artigo foi originalmente publicado em meu site pessoal https://otao.dev.br/conventional-commits-o-que-sao-e-como-usa-los/