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
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 identação do código da rotina de replicação
style(pedido,faturar): remove linha vazia
style(layout): ajuste nas margens na página inicial
Ajuste na margem superior e inferior da página inicial para melhorar o layout da página e tornar a aparência mais limpa e organizada
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
➤ 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!
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.
Acesse a publicação Script para validar commits e saiba como validar commits seguindo o padrão do Conventional Commits.