Git e Versionamento

Regras de versionamento para manter o histórico do código limpo, rastreável e vinculado às tasks. O princípio é simples: todo commit e toda branch devem ser rastreáveis até uma task.

Branches

Formato Obrigatório

KPT-[NUMERO] - descricao-breve

Componentes:

KPT-[NUMERO]: Código da task no gerenciador de tarefas (obrigatório)
descricao-breve: 3-5 palavras descrevendo o trabalho

Exemplos

Branch	O que está sendo feito
`KPT-12313 - integracao-clientes-xhw`	Integração de clientes com sistema XHW
`KPT-12450 - corrigir-calculo-imposto`	Correção no cálculo de imposto
`KPT-12501 - sincronizar-estoque`	Sincronização de estoque automática
`KPT-12600 - relatorio-vendas-mensal`	Novo relatório de vendas mensal
`KPT-12720 - ajuste-trigger-movimento`	Ajuste na trigger de movimento de estoque

Regras

Sempre vincular à task: Sem KPT-XXXXX, a branch não é criada
Descrição curta: Máximo 5 palavras em kebab-case
Sem branches genéricas: Nada de desenvolvimento, teste, ajustes, fix

Erros Comuns

Errado	Correto	Por quê
`minha-feature`	`KPT-12313 - integracao-clientes-xhw`	Sem referência de task
`desenvolvimento`	`KPT-12313 - integracao-clientes-xhw`	Genérico demais, não rastreia nada
`KPT-12313`	`KPT-12313 - integracao-clientes-xhw`	Falta descrição — impossível saber o que é sem abrir a task
`bugfix/ajustes-diversos`	`KPT-12450 - corrigir-calculo-imposto`	"Ajustes diversos" não diz nada

Commits

Formato Obrigatório

KPT-[NUMERO] - descricao breve do que foi feito

Regras

Sempre começar com a task: KPT-XXXXX obrigatório
Descrição clara e curta: O que foi feito (não como)
Imperativo: "adicionar", "corrigir", "remover" (não "adicionado", "corrigindo")
Máximo 72 caracteres na primeira linha
1 commit = 1 mudança lógica: Não misturar coisas diferentes no mesmo commit

Exemplos Bons

KPT-12313 - adicionar service de sincronizacao de clientes
KPT-12313 - criar action button de importacao manual
KPT-12313 - criar trigger de movimento de estoque
KPT-12450 - corrigir calculo de ICMS com substituicao tributaria
KPT-12501 - criar job de sincronizacao a cada 30 minutos
KPT-12600 - criar view de relatorio de vendas mensal

Exemplos Ruins (NÃO FAÇA)

Commit	Problema
`ajustes`	Sem task, sem descrição — inútil no histórico
`fix`	Fix de quê? Onde?
`WIP`	Não commitar trabalho incompleto. Use `git stash`
`KPT-12313`	Sem descrição — obriga abrir a task para entender
`correções diversas e melhorias no código`	Genérico — impossível saber o que mudou
`06/03/2026 - alteração no módulo financeiro`	Data no commit não serve para nada (o Git já registra data). E "alteração" é genérico

Resumo Visual

Branch: KPT-12313 - integracao-clientes-xhw
    │
    ├── Commit: KPT-12313 - criar estrutura inicial do projeto
    ├── Commit: KPT-12313 - adicionar service de sincronizacao
    ├── Commit: KPT-12313 - criar action button de importacao
    ├── Commit: KPT-12313 - criar job de sincronizacao automatica
    └── Commit: KPT-12313 - adicionar tratamento de erros

→ Pull Request → Review → Merge

Princípio: Olhando qualquer commit do histórico, você deve conseguir: (1) saber qual task originou a mudança, e (2) entender o que foi feito sem precisar abrir o diff.