Git profissional

Git Profissional — Fluxo e Versionamento

Visão geral

Git é a sua rede de segurança. Trate commits como pontos de salvamento, branches como caixas de areia e o histórico como documentação. Com agentes de IA gerando código em alta velocidade, a disciplina de versionamento é o mecanismo que mantém as mudanças gerenciáveis, revisáveis e reversíveis.

Quando usar

Sempre. Toda mudança de código passa pelo git.

Quando NÃO usar: não existe cenário — mas as seções de release e versionamento só se aplicam quando há consumidores (outro time, pacote publicado, cliente em produção).

O fluxo

1. Trunk-based development (recomendado)

Mantenha a main sempre implantável. Trabalhe em feature branches de vida curta que voltam para a main em 1 a 3 dias. Branches de desenvolvimento longevas são custo oculto — divergem, criam conflitos e atrasam a integração. A pesquisa DORA mostra consistentemente que trunk-based development se correlaciona com times de alta performance.

main ──●──●──●──●──●──●──●──●──●──  (sempre implantável)
        ╲      ╱  ╲    ╱
         ●──●─╱    ●──╱    ← feature branches curtas (1-3 dias)

Times que usam gitflow ou branches longevas podem adaptar os princípios (commits atômicos, mudanças pequenas, mensagens descritivas) — a disciplina de commit importa mais do que a estratégia de branch.

• Branches de dev são custo. Cada dia de vida de uma branch acumula risco de merge.
• Branches de release são aceitáveis para estabilizar um release enquanto a main avança.
• Feature flags > branches longas. Prefira lançar trabalho incompleto atrás de flags a mantê-lo em branch por semanas.

Nomenclatura: feature/<descricao>, fix/<descricao>, chore/<descricao>, refactor/<descricao>. Apague a branch após o merge.

2. Disciplina de commits

Commit cedo, commit sempre. Cada incremento bem-sucedido ganha o próprio commit: implemente a fatia → teste → verifique → commit → próxima fatia. Nunca acumule mudanças grandes sem commit.

Commits atômicos. Cada commit faz uma coisa lógica:

# Bom: cada commit é autocontido
a1b2c3d Adiciona endpoint de criação de tarefas com validação
d4e5f6g Adiciona componente de formulário de criação
h7i8j9k Conecta formulário à API com estado de loading

# Ruim: tudo misturado
x1y2z3a Adiciona feature de tarefas, conserta sidebar, atualiza deps

Mensagens descritivas explicam o porquê, não só o o quê:

<tipo>: <descrição curta>

<corpo opcional explicando o porquê>

Tipos: feat (funcionalidade), fix (correção), refactor, test, docs, chore.

Separe as preocupações. Não misture formatação com comportamento, nem refatoração com feature — cada tipo de mudança em um commit próprio (idealmente, PR próprio). Limpezas pequenas (renomear uma variável) podem ir junto, a critério do revisor.

Dimensione as mudanças. Alvo de ~100 linhas por commit/PR; até ~300 é aceitável para uma mudança lógica única; acima de ~1000, divida. Veja as estratégias de divisão na skill revisar-codigo.

3. O padrão de ponto de salvamento

Agente inicia o trabalho
    ├── Faz uma mudança
    │   ├── Teste passa? → Commit → Continua
    │   └── Teste falha? → Reverte ao último commit → Investiga
    └── Feature completa → Os commits formam um histórico limpo

Você nunca perde mais de um incremento de trabalho. Se o agente sair dos trilhos, git reset --hard HEAD retorna ao último estado bom conhecido.

4. Resumo de mudanças

Após qualquer modificação, forneça um resumo estruturado com três seções: MUDANÇAS FEITAS (arquivo por arquivo), O QUE NÃO TOQUEI (de propósito) e PONTOS DE ATENÇÃO. A seção "não toquei" é a mais importante — mostra disciplina de escopo e evita reformas não solicitadas. Exemplo completo em referencias/git-avancado.md.

5. Higiene pré-commit

Antes de todo commit: revise git diff --staged, cheque segredos (grep -i "password\|secret\|api_key\|token"), rode testes, lint e checagem de tipos. Automatize com hooks (lint-staged + husky) — configuração em referencias/git-avancado.md, junto com o que commitar de arquivos gerados, uso de worktrees para agentes em paralelo e git para depuração (bisect, blame).

6. Release e versionamento

Commits são como você rastreia mudança; uma versão é como seus consumidores rastreiam. No momento em que algo depende do seu código, "o último da main" deixa de responder "o que estou rodando e é seguro atualizar?". Versão e changelog são o contrato que responde.

Versionamento semântico (MAJOR.MINOR.PATCH):

MAJOR  mudança que quebra — consumidores precisam mudar código para atualizar
MINOR  funcionalidade nova, retrocompatível — seguro atualizar
PATCH  correção de bug, retrocompatível — seguro atualizar

O número é uma promessa. Um "patch" que muda comportamento do qual consumidores dependiam é um major disfarçado (Lei de Hyrum — veja a skill design-de-api). Na dúvida sobre ser breaking, assuma que é: um major surpresa custa muito menos que um consumidor quebrado.

Crie a tag e faça dela a fonte da verdade:

git tag -a v1.4.0 -m "Release 1.4.0"
git push origin v1.4.0

Derive a versão da tag em vez de editá-la à mão em arquivos espalhados — assim artefato, tag e changelog nunca discordam.

Mantenha um changelog escrito para humanos. Changelog não é git log: é a resposta curada, voltada ao consumidor, para "o que mudou e isso me afeta?" — agrupado por Added / Changed / Fixed / Deprecated / Removed / Security, mais novo no topo, cada entrada em termos de impacto no usuário. Escreva a entrada na mesma mudança que a causa, não por arqueologia de commits na hora do release. Mudanças que quebram ganham nota de migração e janela de deprecação (siga a skill migrar); publicar o release é trabalho da skill lancar. Exemplo de changelog em referencias/git-avancado.md.

Racionalizações comuns

Racionalização	Realidade
"Faço commit quando a feature terminar"	Um commit gigante é impossível de revisar, depurar ou reverter. Commit por fatia.
"A mensagem não importa"	Mensagens são documentação. O você do futuro (e os agentes) precisarão entender o que mudou e por quê.
"Depois eu faço squash"	Squash destrói a narrativa do desenvolvimento. Prefira commits incrementais limpos desde o início.
"Branch é burocracia"	Branches curtas são grátis e evitam colisões. O problema são as longevas — faça merge em 1-3 dias.
"Divido essa mudança depois"	Mudanças grandes são mais difíceis de revisar, arriscadas de implantar e duras de reverter. Divida antes de submeter.
"Não preciso de .gitignore"	Até o .env com segredos de produção ser commitado. Configure imediatamente.
"É só um fix, sobe o patch"	Cheque o que os consumidores conseguem observar. Comportamento do qual dependiam é major, seja qual for o tamanho do diff.
"O changelog é o log de commits"	Commits são para você; o changelog é para consumidores, curado por impacto.
"Escrevemos o changelog no release"	Aí o impacto é reconstruído de memória e metade se perde. Escreva a entrada junto com a mudança.

Sinais de alerta

• Mudanças grandes acumuladas sem commit
• Mensagens como "fix", "update", "misc"
• Formatação misturada com mudanças de comportamento
• Projeto sem .gitignore
• node_modules/, .env ou artefatos de build commitados
• Branches longevas divergindo significativamente da main
• Force-push em branches compartilhadas
• Mudança que quebra publicada como minor ou patch
• Release sem tag, ou versão editada à mão fora de sincronia com a tag
• Release para usuários sem entrada de changelog, ou changelog que é só despejo de commits

Portão de aprovação

Apresente: o resumo estruturado de mudanças (feitas / não tocadas / atenções), o histórico de commits proposto e — se for release — o bump de versão com justificativa e a entrada de changelog. O humano aprova: o escopo das mudanças, a classificação major/minor/patch e a publicação da tag. Só avance após aprovação explícita.

Verificação

Para todo commit:

• O commit faz uma coisa lógica
• A mensagem explica o porquê e segue as convenções de tipo
• Testes passam antes do commit
• Nenhum segredo no diff
• Sem mudanças só de formatação misturadas com comportamento
• .gitignore cobre as exclusões padrão

Para todo release (qualquer coisa com consumidores):

• O bump de versão corresponde à mudança: quebra → major, adição → minor, correção → patch
• O release tem tag, e a versão deriva da tag (não editada à mão fora de sincronia)
• O changelog tem entrada curada e legível, agrupada por impacto, para esta versão