Pular para conteúdo

Commit Semântico

Este documento define o padrão Arkorizon para mensagens de commit.

A documentação é em português, mas a mensagem do commit deve ser escrita em inglês. Isso mantém compatibilidade com automações, changelogs, ferramentas de release e leitura por times internacionais.

Escopo do documento

Este documento fala apenas sobre mensagens de commit. Branch naming, Pull Requests e release/versionamento ficam em documentos separados.

Padrão obrigatório

<type>(<scope>): <summary>

O scope é opcional, mas recomendado quando ajuda a entender a área alterada dentro do repositório atual.

Exemplos:

feat(auth): add refresh token rotation
fix(api): reject inactive users during login
docs(workflow): explain semantic commit format
ci(pages): add MkDocs deployment workflow

O que o commit deve comunicar

Um bom commit responde rapidamente:

  • que tipo de mudança foi feita;
  • qual área do repositório foi afetada;
  • qual resultado a mudança entrega.

Ele não precisa contar o nome completo do produto, porque o commit já está dentro de um repositório específico.

Ruim:

feat(product-agent): add local file indexing

Melhor dentro do repositório do agent:

feat(indexing): add local file indexing

Ruim:

docs(repository-name): expand repository standards

Melhor dentro do repositório atual:

docs(standards): expand repository organization guide

Types oficiais

Type Quando usar
feat Nova funcionalidade ou capacidade.
fix Correção de bug.
docs Alterações apenas em documentação.
style Formatação sem mudança de comportamento.
refactor Refatoração sem mudança funcional.
perf Melhoria de performance.
test Criação ou ajuste de testes.
build Build, dependências, empacotamento ou artefatos.
ci Workflows, pipelines e automações de CI/CD.
chore Manutenção sem impacto direto no comportamento.
security Correção ou melhoria de segurança.
revert Reversão de commit anterior.

Como escolher o scope

O scope deve ser uma área interna do repositório atual.

Bons scopes:

auth
api
persistence
cache
security
workflow
standards
architecture
pages
build

Evite usar como scope:

  • nome completo do produto;
  • nome completo do repositório;
  • groupId Java;
  • artifactId Maven;
  • nome de imagem Docker;
  • nome da organização.

O groupId identifica artefatos Java em repositórios de pacotes. Ele não deve dirigir mensagens de commit.

Regras da primeira linha

A primeira linha deve:

  • estar em inglês;
  • usar verbo no imperativo ou presente simples;
  • ter no máximo 72 caracteres sempre que possível;
  • não terminar com ponto final;
  • não usar emoji;
  • não usar acento;
  • explicar resultado, não atividade vaga.

Bom:

fix(auth): reject inactive users during login

Ruim:

fix(auth): fixed bug

Corpo do commit

Use corpo quando a mudança precisa de contexto.

refactor(auth): isolate token generation behind output port

Moves JWT generation to a dedicated adapter so the login use case no longer
depends on Spring Security token infrastructure.

O corpo deve explicar:

  • o que mudou;
  • por que mudou;
  • impacto esperado;
  • decisões relevantes.

Evite explicar linha por linha como o código foi alterado.

Rodapé

Use rodapé para issues, referências e breaking changes.

Refs: #42
Closes: #87

Breaking changes

Quando a mudança quebra compatibilidade, use ! e adicione BREAKING CHANGE no rodapé.

feat(auth)!: replace legacy token format

BREAKING CHANGE: clients must update token parsing to support the new JWT claims.

Commits atômicos

Um commit deve representar uma unidade coesa de mudança.

Bom:

feat(auth): add login use case
feat(auth): add refresh token persistence port
test(auth): cover invalid credentials flow

Ruim:

feat(auth): add login, update docs, refactor database and fix tests

Um commit pode ser grande somente quando separar a mudança deixaria o projeto inconsistente, quebrado ou impossível de validar.

Exemplos bons

feat(auth): add refresh token rotation
fix(api): normalize email before lookup
docs(workflow): add pull request standards
ci(pages): configure MkDocs deployment
build(maven): publish release artifact
test(auth): cover invalid credentials flow
refactor(persistence): isolate user repository adapter
security(auth): enforce account lockout policy

Exemplos ruins

update stuff
ajustes gerais
final commit
fixando bugs
mudanças
feat: stuff
fix: bug
docs(developer-handbook): updates
feat(com.company.product.auth): add login

Relação com versionamento

Commits semânticos podem alimentar automações de release, changelog e SemVer. Este documento define apenas o formato da mensagem de commit.

As regras de versionamento ficam em Release e Versionamento.

Checklist antes do commit

  • A mensagem está em inglês.
  • O type está na lista oficial.
  • O scope representa uma área do repositório atual.
  • A primeira linha descreve resultado.
  • O commit é coeso.
  • O projeto compila ou a documentação builda.
  • Breaking change foi marcada corretamente.
  • Issues relacionadas foram referenciadas quando necessário.

Regra final

O histórico Git deve permitir que alguém entenda a evolução do projeto sem abrir todos os diffs.

Se a mensagem não explica claramente o valor da mudança, ela deve ser reescrita.