Pular para conteúdo

Plataforma - Governanca de Merge e Release

Objetivo

Dar rastreabilidade real ao fluxo de merge e release, especialmente quando houver:

  • PRs empilhados (stacked PRs);
  • PRs de release gerados por automacao;
  • remediation manual em checks, status ou absorcao em master.

Problema que este processo evita

Um PR pode aparecer como MERGED na interface do GitHub e, ainda assim, gerar ambiguidade operacional:

  • foi mergeado numa branch intermediaria, e nao em master;
  • foi mergeado fora da ordem da pilha;
  • o commit ainda nao foi absorvido em origin/master;
  • a UI do GitHub mostra check stale ou faltando, mas o backend dos Actions ja concluiu;
  • a equipe fecha issue e card cedo demais.

Esse processo existe para responder com clareza:

  1. o que foi mergeado;
  2. onde foi mergeado;
  3. se o commit ja esta em master;
  4. em qual etapa do processo ocorreu um erro.

Regras canônicas

1. PR base vs PR empilhado

  • o PR base aponta para main ou master;
  • o PR empilhado aponta para a branch do PR base;
  • o PR empilhado deve declarar explicitamente sua dependencia;
  • o topo da pilha nunca deve ser tratado como entregue antes da absorcao completa da base.

2. Ordem de merge

Ordem correta:

  1. merge do PR base;
  2. confirmacao de absorcao em origin/main ou origin/master;
  3. atualizacao do PR dependente para nova base se necessario;
  4. merge do PR dependente;
  5. nova confirmacao de absorcao em origin/main ou origin/master.

3. Definicao de "entregue"

Um bloco so pode ser tratado como entregue quando todos os itens abaixo forem verdadeiros:

  • PR aparece como MERGED;
  • commit aparece em origin/main ou origin/master;
  • issue correspondente foi atualizada ou fechada;
  • card no GitHub Projects foi sincronizado;
  • handoff registrou o bloco, validacao e risco residual.

Se o PR estiver MERGED, mas o commit ainda nao estiver em master, o status correto e:

  • mergeado na pilha, mas nao absorvido na branch principal.

Checklist operacional

Antes do merge

  • confirmar base e head do PR;
  • confirmar se o PR esta empilhado sobre outro;
  • confirmar checks obrigatorios;
  • confirmar plano de rollback do bloco.

Depois do merge

  • confirmar mergedAt;
  • confirmar commit/merge commit;
  • confirmar que o commit esta contido em origin/main ou origin/master;
  • confirmar que issue e card foram atualizados;
  • registrar no handoff qualquer remediation manual.

Release PRs

Para PRs de release:

  • confirmar o estado real dos checks via CLI/API, nao apenas pela UI;
  • se a UI estiver stale, usar remediation controlada para re-disparar o CI na branch do PR;
  • registrar remediation manual na issue/card;
  • so tratar o release como concluido depois da absorcao real em main/master.

Evidencias minimas de rastreabilidade

Toda trilha de merge/release deve deixar:

  • issue correspondente;
  • card no GitHub Projects com Status, Progress, Risk, Updated At e Commit quando houver;
  • PR com validacao e risco residual;
  • handoff em .context/05_handoff.md;
  • doc canônica ou Wiki quando houver mudanca de processo.

Diagnostico rapido de erro de processo

Se algo der errado, perguntar nesta ordem:

  1. o PR foi mergeado na branch certa?
  2. o commit esta realmente em origin/master?
  3. a ordem da pilha foi respeitada?
  4. os checks obrigatorios eram reais ou havia UI stale?
  5. o GitHub Projects foi atualizado cedo demais?

Essa ordem ajuda a localizar se a falha ocorreu em:

  • branching;
  • merge;
  • CI/checks;
  • absorcao em master;
  • governanca/registro.