GovBR-DS - Commitlint Config

Objetivo

Compartilhar uma convenção de commits clara e verificável entre os projetos do GovBR-DS.

Além de validar o formato das mensagens, esta configuração prepara os commits para:

• gerar changelogs legíveis;
• calcular versões automaticamente com Semantic Release;
• relacionar commits a issues do GitLab;
• explicar ao próximo desenvolvedor o contexto e o impacto da mudança.

Formato

As mensagens seguem o formato do Conventional Commits:

tipo(escopo): resumo

corpo opcional com contexto, causa e impacto

rodapé opcional, como Closes #123

Exemplo:

fix(datepicker): validar data máxima antes de emitir o evento

A data máxima era ignorada quando o valor vinha do teclado, permitindo um estado inválido.

Closes #123

Tipo

Indica a intenção da mudança. Escolha o tipo pelo efeito da alteração, não pelo arquivo modificado.

| Tipo | Quando usar | Efeito no release | | ------------ | -------------------------------------------------------- | ------------------------------- | | feat | Nova capacidade ou comportamento compatível | minor | | fix | Correção de comportamento incorreto | patch | | docs | Documentação, exemplos e guias | patch | | perf | Melhoria de desempenho sem alterar a API | patch | | refactor | Reorganização interna sem mudar comportamento | patch | | removed | Remoção definitiva de API ou recurso público | major | | revert | Reversão de uma mudança publicada | minor | | deprecated | Marcação de API ou recurso como obsoleto | Sem release automático | | build | Build, bundler ou dependências de desenvolvimento | Sem release automático | | chore | Manutenção interna sem efeito no produto | Sem release automático | | ci | Pipelines, jobs e automações de CI | Sem release automático | | lint | Formatação e estilo sem mudança executável | Sem release automático | | ops | Atividades operacionais de design ou desenvolvimento | Sem release automático | | site | Site ou documentação publicada fora do pacote | Sem release automático | | test | Criação ou ajuste de testes | Sem release automático | | wip | Trabalho incompleto; não deve chegar à branch de release | Sem release automático | | bump | Atualização manual de versão | Evite; prefira Semantic Release |

Os tipos sem release continuam disponíveis para manter o histórico consistente e permitir que o changelog diferencie mudanças de produto de manutenção interna.

Escopo

Indica a área alterada. Use um nome curto, específico e estável:

fix(button): corrigir foco após o clique
feat(tokens): adicionar cor semântica de informação
docs(install): explicar instalação via pnpm

O escopo não deve ser minor ou patch para forçar uma versão. A versão é determinada pelo tipo e pelas breaking changes.

Resumo

Escreva um resumo curto, objetivo e no infinitivo:

feat: adicionar suporte a tema escuro
fix(menu): corrigir fechamento ao pressionar Escape

Evite ponto final, frases vagas e referências sem contexto como fix: issue 123.

Corpo

Use o corpo quando o título não explicar a decisão. Responda, quando fizer sentido:

• qual era o problema;
• por que ele acontecia;
• qual comportamento foi alterado;
• qual impacto existe para quem usa o projeto.

Ao usar o czg, digite | para inserir uma quebra de linha manualmente. Se não for necessário separar o texto, não use esse caractere.

Issues

Relacione a issue no rodapé:

Closes #123

Use Closes, Fixes ou Resolves quando o commit deve fechar a issue após o merge. Use apenas #123 quando a issue deve ser relacionada, mas permanecer aberta.

Breaking changes

Uma breaking change altera ou remove um contrato que consumidores existentes dependem. Exemplos:

• remover uma propriedade, evento, método ou componente;
• tornar obrigatório um campo antes opcional;
• mudar o formato de retorno;
• alterar comportamento esperado de forma incompatível.

Marque a mudança no cabeçalho ou no rodapé e explique como migrar:

feat(api)!: tornar token obrigatório

BREAKING CHANGE: o token não é mais aceito como propriedade opcional. Envie-o no cabeçalho Authorization.

Toda breaking change gera uma versão major, independentemente do tipo escolhido.

No czg, responda que o commit é uma breaking change para abrir o campo de incompatibilidade e migração. Esse campo não aparece para commits compatíveis.

Instalação

pnpm add -D @govbr-ds/commitlint-config @commitlint/cli czg husky

O czg é opcional: instale-o apenas se quiser usar o prompt interativo. O @commitlint/cli é necessário para validar os commits, e o husky é necessário apenas para executar essa validação automaticamente no commit local.

Configuração

Crie .commitlintrc.js na raiz:

export default {
  extends: ['@govbr-ds/commitlint-config'],
}

O exemplo usa export default; portanto, o projeto deve usar módulos ES ("type": "module" no package.json). Em projetos que não usam módulos ES, utilize a extensão de configuração compatível com a versão do commitlint instalada.

Para usar o czg, crie cz.config.cjs na raiz e reutilize a configuração compartilhada:

module.exports = require('@govbr-ds/commitlint-config/czg')

Adicione o czg ao package.json:

{
  "scripts": {
    "commit": "czg --config=./cz.config.cjs",
    "prepare": "husky"
  }
}

Inicialize o Husky e crie o hook .husky/commit-msg:

pnpm exec husky init

No arquivo .husky/commit-msg, use:

pnpm exec commitlint --edit "$1"

Adicione o script prepare caso ele ainda não exista, para que o Husky seja configurado após a instalação das dependências:

{
  "scripts": {
    "prepare": "husky"
  }
}

Execute pnpm commit (ou o script equivalente configurado no projeto) para abrir o prompt interativo. O czg reutiliza os tipos compartilhados, oferece a marcação de breaking change e gera a mensagem; o hook do commitlint continua sendo a validação obrigatória, inclusive para mensagens criadas manualmente.

O hook impede mensagens inválidas no commit local. O pipeline deve executar a mesma validação para proteger commits criados sem os hooks locais.

Exemplos rápidos

feat(header): adicionar navegação responsiva
fix(input): preservar valor ao exibir mensagem de erro
docs(tokens): explicar token de superfície
refactor(core): separar parser de validação
test(select): cobrir navegação por teclado
ci: atualizar imagem do pipeline

Contribuição

Antes de abrir um Merge Request, consulte o guia de contribuição e mantenha esta documentação alinhada com as regras do pacote release. Alterações em tipos, regras ou impacto SemVer devem incluir exemplos de mensagens válidas e inválidas.

Licença

Este projeto utiliza a licença MIT.