Pular para o conteúdo
Manifestomanifesto.jhow.net

7. Padrões · versão 2.0.0

Git e commits

manifesto/architecture/11-git-e-commits.md

Fluxo de branches

O Manifesto usa um fluxo leve: a develop é a branch de trabalho.

  • develop é onde se trabalha no dia a dia. Pode commitar direto na develop.
  • main (quando existir) guarda releases estáveis. Promover develop → main é decisão por projeto, não um portão fixo.
  • Uma branch por ADR é opcional numa sessão só; com agentes em paralelo, é a regra: cada frente no seu worktree e na sua branch, integrada por merge local, uma de cada vez, com a trava (ver Orquestração de agentes).

Sem pull request

O ecossistema do Manifesto é o git, não o GitHub: o repositório remoto é onde o código fica guardado, não o lugar onde se trabalha. Não se abre pull request — é um passo visual que pede o site ou um MCP do GitHub e não acrescenta nada ao que a ADR já registra (a decisão, o plano, a revisão, os relatórios). Integrar é o merge local (git merge --no-ff <branch>), e a revisão é a da própria ADR (o 004 e, num workflow, a revisão adversarial).

Push só com autorização

  • O git push é feito quando o dono pede, ou com a autorização dele naquela vez: a IA pode oferecer (“quer que eu faça o push?”) e espera o sim. Uma autorização vale para aquele push, não para os próximos.
  • Nunca --force (nem --force-with-lease) sobre o que já foi empurrado.
  • Agente secundário e workflow nunca fazem push: só a sessão principal, com a autorização do dono (ver Orquestração de agentes).
  • As etiquetas (git push origin <etiqueta>) seguem a mesma regra.

Commits

  • Conventional Commits obrigatório (feat:, fix:, docs:, refactor:, …).
  • O commit cita a tarefa e a ADR no rodapé (ver abaixo): é o que amarra o código ao trabalho sem ninguém manter lista à mão.
  • Commits que alteram a documentação de uma ADR podem usar o prefixo adr/docs:.
  • Commit seletivo: prefira não usar git add . quando houver arquivos fora do escopo.

Tarefa e ADR no rodapé

O rodapé da mensagem (depois de uma linha em branco, no fim) leva uma linha por referência:

feat(gestor): a gaveta da ADR no modal do item


Abre a ADR vinculada ao lado do item, com o leitor da Documentação.


Tarefa: KBP-12
ADR: 098
  • Tarefa: <IDENTIFICADOR> — a tarefa do Gestor (KBP-12); uma linha para cada tarefa.
  • ADR: <NNN> — o número da ADR (098); uma linha para cada ADR.
  • Só o que existe: sem tarefa, sem a linha Tarefa:; o commit que não é de uma ADR (raro: um merge, um ajuste de ferramenta local) fica sem ADR:.
  • O leitor do Gestor aceita também as referências no fim do assunto, entre parênteses — feat(gestor): a gaveta da ADR (KBP-12, ADR 098) —, mas o padrão é o rodapé: não encurta o assunto e aceita várias tarefas.
  • O Gestor lê os commits na hora, do git (nada guardado), e os mostra no item da tarefa e na página da ADR, só à equipe (mensagens e autores são internos).
  • Outras linhas de rodapé (Co-Authored-By:, BREAKING CHANGE:) convivem com estas, cada uma na sua linha.

Regras duras de git

Poucas, e só as que evitam estrago:

  • Não usar git reset --hard nem git push --force sobre trabalho compartilhado.
  • Não fazer git push sem o pedido ou a autorização do dono (acima).
  • Não usar --no-verify para furar hooks de qualidade.

Recomendações

  • 1 passo = 1 commit (um passo do 004; pode conter vários detalhes) — recomendação que mantém o histórico limpo e rastreável, não regra dura.
  • SemVer + tags nas releases: decisão por projeto.
  • Hooks de pré-commit (husky/lefthook) e CI: opcionais, nascem em ADR quando úteis.