O Conventional Commits (Commits Convencionais) é uma especificação para mensagens de commit que adiciona um conjunto de regras para criar um histórico de versionamento explícito e estruturado. Essa padronização facilita a colaboração entre desenvolvedores e permite a automação de processos, como a geração de logs de mudanças (changelogs) e a determinação da próxima versão semântica do software.

Estrutura das Mensagens

Uma mensagem de commit seguindo esta convenção deve ter a seguinte anatomia:

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

[corpo opcional]

[rodapé(s) opcional(is)]

Os principais tipos utilizados são:

• feat: Adição de uma nova funcionalidade (corresponde ao MINOR no Versionamento Semântico).
• fix: Correção de um erro no código (corresponde ao PATCH no Versionamento Semântico).
• BREAKING CHANGE: Uma alteração que quebra a compatibilidade com versões anteriores (corresponde ao MAJOR). Pode ser indicada por um ! após o tipo/escopo ou no rodapé.
• docs: Alterações apenas na documentação.
• style: Mudanças que não afetam o sentido do código (espaços, formatação, pontos e vírgulas ausentes).
• refactor: Alteração de código que não corrige bugs nem adiciona funcionalidades.
• perf: Mudança de código focada em melhoria de desempenho.
• test: Adição ou correção de testes existentes.
• chore: Atualizações em tarefas de build, configurações de ferramentas ou pacotes.

Implementação com Commitizen

O Commitizen é uma ferramenta de linha de comando que transforma o processo de commit em uma interface interativa, garantindo que o desenvolvedor siga as regras estabelecidas sem precisar decorar a sintaxe.

Configuração Inicial

Para instalar globalmente e configurar o adaptador padrão:

pnpm install -g commitizen cz-conventional-changelog
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc

Com isso, em vez de usar git commit, você pode utilizar git cz para abrir o asssistente de preenchimento.

Customização com cz-customizable

Muitas vezes, as equipes precisam de tipos de commit específicos ou traduções. O plugin cz-customizable permite essa flexibilidade.

1. Instale a dependência de desenvolvimento:

npm install cz-customizable --save-dev

2. Configure o package.json para apontar para o novo adaptador:

"config": {
  "commitizen": {
    "path": "node_modules/cz-customizable"
  }
}

3. Crie um arquivo .cz-config.js na raiz do projeto para definir as regras personalizadas:

module.exports = {
  types: [
    { value: 'feat', name: 'feat:     Nova funcionalidade' },
    { value: 'fix', name: 'fix:      Correção de bug' },
    { value: 'docs', name: 'docs:     Alteração em documentação' },
    { value: 'style', name: 'style:    Ajustes de formatação/estilo' },
    { value: 'refactor', name: 'refactor: Refatoração de código' },
    { value: 'perf', name: 'perf:     Melhoria de performance' },
    { value: 'chore', name: 'chore:    Ajustes em ferramentas de build' },
    { value: 'revert', name: 'revert:   Reversão de commit' }
  ],
  messages: {
    type: 'Selecione o tipo de alteração:',
    scope: 'Escopo da alteração (opcional):',
    subject: 'Descrição curta e direta:',
    body: 'Descrição detalhada (opcional). Use "|" para quebras de linha:',
    footer: 'Listagem de problemas resolvidos (ex: #123):',
    confirmCommit: 'Deseja prosseguir com o commit acima?'
  },
  subjectLimit: 80
};

Validação com Commitlint

Para impedir que commits fora do padrão cheguem ao repositório, utilizamos o commitlint. Ele analisa a mensagem e rejeita o committ caso ele não siga as regras.

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

Crie o arquivo commitlint.config.js:

module.exports = {
  extends: ['@commitlint/config-conventional']
};

Automação com Husky e lint-staged

O Husky permite gerenciar Git Hooks de forma simples, executando scripts em momentos específicos, como antes de um commmit (pre-commit) ou ao validar a mensagem de commit (commit-msg).

Configurando o Husky

Instale o Husky:

pnpm install husky --save-dev
npx husky install

Adicione o hook de validação de mensagem:

npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

Filtragem com lint-staged

Para garantir a qualidade do código antes mesmo do commit, o lint-staged executa comandos apenas nos arquivos que foram modificados e estão na área de stage.

Instalação:

npm install lint-staged --save-dev

No package.json, defina as tarefas de limpeza:

"lint-staged": {
  "*.{js,ts,tsx}": [
    "eslint --fix",
    "prettier --write"
  ],
  "*.json": [
    "prettier --write"
  ]
}

Por fim, adicione o comando ao hook de pre-commit do Husky:

npx husky add .husky/pre-commit "npx lint-staged"

Com essa arquitetura, o fluxo de trabalho torna-se robusto: o código é formatado e validado automaticamente, e as mensagens de commit seguem um padrão rigoroso que permite a rastreabilidade total da evolução do projeto.