Conventional Commits

O Conventional Commits é uma forma de padronização de commits dentro de um projeto de desenvolvimento de software, utilizando regras simples e claras com o objetivo de tornar os commits mais descritivos e padronizados, contribuindo para reduzir o tempo gasto em compreender como e por que algo foi feito em uma alteração ou correção posterior.

Formato do commit

A mensagem do commit deve ser estruturada da seguinte forma:

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

[corpo opcional]

[rodapé opcional]

Tipo

O tipo determina a natureza do commit, que pode variar de acordo com as mudanças realizadas no código, podendo ser uma das opções abaixo:

TIPO	DESCRIÇÃO
feat	Adiciona uma nova funcionalidade/recurso
fix	Corrige um bug (falha no sistema/comportamento inesperado)
style	Ajustes na apresentação do código (não altera comportamento), como remoção de espaços em branco, indentação, entre outros
refactor	Reescreve/Reestrutura o código (não altera comportamento), busca melhorar a qualidade e a organização do código
perf	Reescreve/Reestrutura o código melhorando o desempenho
test	Adiciona ou atualiza testes automatizados para garantir a qualidade do sistema
docs	Adiciona ou atualiza documentação, como documentação de métodos, APIs, READMEs, entre outros
build	Indica alterações no processo de construção do software, como configurações de compilação, build, configurações do docker, entre outros
ci	Alterações em configurações de integração contínua, como ferramentas de análise de código
chore	Mudanças que não afetam o comportamento visível do software, usado para tarefas de manutenção e outras tarefas que não se enquadram em nenhum dos tipos acima
revert	Reverter o código para um commit anterior

Obs: É uma parte obrigatória do commit.

Escopo (opcional)

O escopo fornece informações contextuais do commit. Um resumo em uma ou duas palavras das modificações realizadas ou, por exemplo, o nome do módulo do sistema no qual foram realizadas as modificações.

Descrição

A descrição apresenta de forma sucinta as mudanças realizadas no commit.

Obs: É uma parte obrigatória do commit.

Corpo (opcional)

O corpo apresenta uma descrição detalhada das modificações e pode incluir, por exemplo, a motivação para as mudanças ou uma breve explicação da diferença para o comportamento anterior.

Rodapé (opcional)

O rodapé apresenta informações adicionais, por exemplo o número de tarefa ou bibliotecas relacionadas.

Exemplos de Commits

Diversos exemplos de commits para cada tipo.

feat

feat(linguagem): adiciona tradução para português brasileiro

feat(estoque): adiciona opção para filtrar registros pela descrição

feat(paypal,pagamento)!: adiciona nova funcionalidade de pagamento via PayPal

A funcionalidade foi implementada adicionando um botão de "Pagar com PayPal" à página de checkout e integrando o backend do site com a API do PayPal

BREAKING CHANGE: Este commit modifica a API de pagamento para suportar o PayPal. Os clientes que usam a versão anterior da API precisarão atualizar seus clientes para usar a nova versão

O que é uma BREAKING CHANGE?

A palavra-chave "BREAKING CHANGE" é usada para indicar uma alteração importante no software que pode afetar a compatibilidade com versões anteriores e quebrar o funcionamento de outras partes do sistema. Essa informação é útil para outros desenvolvedores que talvez precisam atualizar seus próprios sistemas para acomodar as mudanças feitas.

Uma BREAKING CHANGE pode ser indicada no rodapé com a palavra-chave ou com o símbolo "!" depois do tipo/escopo.

fix

fix: corrige erro de digitação em mensagem de erro ao faturar

fix: corrige erro de compilação em versões antigas do sistema operacional

Refs: CS-112

fix(auth): corrige erro de autenticação ao usar autenticação biométrica

O erro foi corrigido atualizando a biblioteca de autenticação biométrica para uma versão mais recente

Refs: CS-113

style

style: atualiza indentação do código da rotina de replicação

style(pedido,faturar): remove linha vazia

style(layout): padroniza a indentação do componente da página inicial

Padroniza os espaços em branco do componente sem alterar a aparência da página

refactor

refactor: atualiza método após code review

refactor: simplifica lógica do if else

refactor(layout): reestrutura componentes de layout

O código foi separado em componentes menores e mais específicos para facilitar a identificação e correção de problema

perf

perf: otimiza algoritmo de busca dos dados para melhorar tempo de resposta

perf: melhora tempo de resposta da página de login

perf(componente): atualiza lógica de renderização de gráfico

Utiliza uma abordagem mais eficiente para calcular e renderizar os dados, reduzindo o tempo de carregamento e melhorando a interatividade do usuário

test

test: adiciona testes unitários para rotina de faturamento

test(service): adiciona teste unitário para a função de validação de senha

Teste unitário para a função validatePassword() usando senhas de diferentes níveis de complexidade para verificar se a função retorna true ou false para cada uma

test(service): adiciona testes para o serviço de notificações

Garante que as notificações sejam enviadas corretamente para os usuários e que as notificações sejam exibidas corretamente na interface do usuário

docs

docs: atualiza documentação da API de logs

docs: corrige ortografia no changelog

docs(instalacao): atualiza documentação de instalação

A documentação de instalação foi atualizada com informações sobre as versões mais recentes do software e os requisitos de sistema

build

build: atualiza versão do compilador

build(docker): atualiza configurações do Dockerfile

Adiciona novas etapas para garantir que as dependências do projeto estejam instaladas corretamente

build(dev): corrige configuração do ambiente de desenvolvimento

Ajusta variáveis de ambiente para os scripts funcionarem corretamente no ambiente de desenvolvimento

ci

ci: adiciona etapa de verificação de segurança no pipeline de CI

ci: adiciona integração com ferramenta de análise de vulnerabilidades

ci(github-actions): atualiza fluxo de trabalho do GitHub Actions

Atualiza fluxo para garantir que os testes sejam executados corretamente em diferentes versões do sistema operacional e dos navegadores

chore

chore: atualiza dependências do projeto

chore!: remove suporte para Node 6

BREAKING CHANGE: refatora para usar recursos do JavaScript não disponíveis no Node 6

chore: resolve merge conflict

Resolvido conflito de merge devido a uma mudança não relacionada feita por outro desenvolvedor

revert

revert: reverte commit realizado na branch errada

Observações e Sugestões

• Um detalhe muito importante ao utilizar esse padrão de commits é utilizar o modo de escrita imperativo.

Correto:

feat(mvcp): adiciona mvcp contratos

Errado:

feat(mvcp): adicionado mvcp contratos

Você deve sempre descrever o que esse commit vai fazer e não o que você fez no commit!

• Não capitalizar a primeira letra, ou seja, não escrever o commit com a primeira letra da descrição em maiúsculo.

Isso não é uma obrigação, mas é um detalhe importante para entrar em consenso se você trabalha em equipe. Além disso, também é interessante definir um padrão se o commit será escrito apenas utilizando letras minúsculas ou não.

• Não utilizar ponto final "." ao escrever o commit.

• Múltiplos escopos devem ser separados por "," ou "/".

Uma sugestão é sempre definir um padrão entre um dos dois, principalmente trabalhando em equipe.

• Definir um limite de caracteres para a descrição do commit.

O objetivo da descrição, é explicar o commit de forma resumida, dessa forma a descrição pode ter um limite de caracteres (Por exemplo: No máximo 80 caracteres).

Caso seja necessário detalhar as modificações, isso deve ser realizado no corpo do commit!

Ainda está na dúvida se o Conventional Commits é uma boa ideia?

As mensagens de commit escritas com base no Conventional Commits podem ser processadas automaticamente por ferramentas como o semantic-release, que utiliza as informações fornecidas nos commits para determinar a próxima versão do software e gerar um changelog automaticamente

Mais informações podem ser encontradas no site oficial do Conventional Commits.