Gestão de branches — SGApi

Guia operacional para o time: estratégia main + staging, fluxos, responsabilidades, quando criar ou quebrar branches, e integração com CI/CD.

Decisão formal: ADR 003 — Estratégia de branches.

---

1. Visão geral

1.1 Modelo adotado

Utilizamos duas branches permanentes que representam ambientes reais:

┌─────────────────────────────────────────────────────────────┐
│  Branches temporárias (dias, no máximo ~1 semana)           │
│  feature/*  fix/*  hotfix/*  refactor/*  chore/*  spike/*   │
└───────────────────────────┬─────────────────────────────────┘
                            │ Pull Request + CI
                            ▼
                    ┌───────────────┐
                    │    staging    │  ← Homologação (QA, E2E, smoke)
                    └───────┬───────┘
                            │ Pull Request + validação completa
                            ▼
                    ┌───────────────┐
                    │     main      │  ← Produção (tag v*, deploy)
                    └───────────────┘

Princípio: tudo que entra em staging deve estar potencialmente deployável. Tudo que entra em main já passou por homologação.

1.2 Por que não usamos develop ou release/*

Abordagem	Problema no contexto SGApi
develop longa	Integração atrasada; conflitos; testes MySQL só no fim
release/* congelada	Deploy de API única não exige gelo de semanas; tags em main bastam
Branch por ambiente (prod, homolog)	Drift de código; difícil saber o que está onde

staging funciona como preview de produção, não como lixeira de experimentos.

1.3 Paridade com testes locais

O script scripts/test.ps1 executa, em ordem:

1. Architecture tests (-c Debug)
2. Unit tests
3. Integration tests — MySQL 8.0 e 5.5

O CI em PRs para staging deve espelhar essa ordem e cobrir ambas as versões MySQL.

---

2. Branches permanentes

2.1 staging

Aspecto	Definição
Propósito	Ambiente de homologação compartilhado
Deploy	Automático após merge (API, workers se aplicável)
Conteúdo	Conjunto de features/fixes aprovados em PR, aguardando QA
Quem mergeia	Via PR apenas; nunca push direto
Estado ideal	Sempre deployável; próximo candidato a main

Objetivos em homologação:

• QA manual (SuperApp + rotas afetadas)
• Testes integrados entre API, frontend e banco de homolog
• Smoke tests e E2E documentados em docs/testing/integration/
• Validação de migrations e seeds em ambiente “quase prod”

Regra de ouro: staging deve ser quase produção:

• Mesma imagem Docker (tag diferente, ex.: :staging ou SHA)
• Mesmas versões de runtime (.NET 10, MySQL compatível)
• Mesmos containers e scripts de migration
• Diferem apenas: secrets, domínio/URL, recursos (CPU/RAM), dados (BD de homolog)

2.2 main

Aspecto	Definição
Propósito	Código em produção (ou pronto para deploy imediato)
Deploy	Automático após merge de staging → main + tag
Tags	vMAJOR.MINOR.PATCH (ex.: v1.4.2)
Quem mergeia	Via PR staging → main; aprovação explícita (tech lead / release owner)

Após merge em main:

• Deploy produção
• Migrations (se houver)
• Checks de observabilidade (/ping, alertas)
• Release notes / comunicação interna

2.3 Sincronização main → staging

Sempre que main avançar sem passar por staging (hotfix), é obrigatório atualizar staging:

hotfix merge em main
       │
       ├── tag v1.3.1
       └── merge ou cherry-pick imediato → staging

Cadência recomendada: no mesmo dia do hotfix, no máximo na manhã seguinte.

Se staging ficar atrás de main, homologação valida código diferente do que está em produção — isso anula o propósito do modelo.

---

3. Branches temporárias

Todas nascem a partir de staging atualizada, exceto hotfix/* (nasce de main).

Após merge, deletar a branch (GitHub: Automatically delete head branches).

3.1 feature/* — nova funcionalidade

Quando usar: novo endpoint, nova regra de negócio, nova subfeature em src/Features/.

Nomenclatura:

feature/<area>-<descricao-curta>
feature/comercial-criar-pedido
feature/auth-refresh-token-rotacao

Incluir ID de chamado quando existir: feature/043447-ajuste-estoque-transacao.

Fluxo:

staging → feature/comercial-criar-pedido → PR → staging

Critérios de PR:

• CI verde (architecture, unit, integration 8.0 + 5.5)
• Testes de mutação assertam todas as tabelas afetadas (ver docs/testing/strategy/README.md)
• Revisão de código (mín. 1 aprovador)
• Descrição com: chamado, rotas, tabelas tocadas, como testar em homolog

---

3.2 fix/* — correção não crítica

Quando usar: bug reproduzível, impacto limitado, produção não está parada.

Nomenclatura:

fix/<id-ou-descricao>
fix/043447-es1-nao-atualiza-saldo
fix/paginacao-offset-negativo

Fluxo: igual a feature/* → PR → staging → QA → depois promoção com o restante de staging → main.

Não usar hotfix/ se o problema pode esperar o ciclo normal de homologação.

---

3.3 hotfix/* — correção crítica em produção

Quando usar:

• Produção indisponível ou funcionalidade crítica quebrada (login, venda, estoque)
• Decisão de negócio de corrigir antes do próximo ciclo staging → main
• Impacto financeiro ou operacional imediato

Nomenclatura:

hotfix/<descricao-curta>
hotfix/pagamento-duplicado
hotfix/043447-es1-saldo

Fluxo:

main ──► hotfix/pagamento-duplicado
              │
              ├── PR → main  (prioridade máxima, CI completo)
              │         └── tag v1.3.1 → deploy prod
              │
              └── PR → staging  (mesmo dia)

Checklist hotfix (obrigatório no PR):

• Bug confirmado em produção (evidência: log, chamado, repro)
• Teste de integração cobrindo o cenário (ou adicionado no PR)
• Escopo mínimo — sem “aproveitar” para refatorar
• staging sincronizado após merge em main
• Comunicação: suporte / produto informados

---

3.4 refactor/* — mudança estrutural

Quando usar:

• Migração de namespaces (WSLinear → SGApi)
• Reorganização vertical slice
• Extração de calculadoras/services
• Mudanças em testes arquiteturais / baseline ADR 002

Comportamento externo: não deve mudar (mesmas rotas, mesmos contratos JSON).

Nomenclatura:

refactor/migracao-namespace-sgapi
refactor/comercial-ajuste-estoque-calculator

Fluxo: PR → staging → QA de regressão (smoke amplo) → main.

Refactors grandes podem exigir janela de homologação dedicada (ver seção 6).

---

3.5 chore/* — manutenção

Quando usar: CI, docs, Dependabot, scripts, Dockerfile, rules Cursor, sem alteração de regra de negócio.

chore/ci-github-actions
chore/atualizar-fluentassertions
chore/docs-gestao-branches

Fluxo: PR → staging (deploy homolog opcional se só docs) → main no próximo release batch ou imediato se só tooling.

---

3.6 spike/* — investigação

Quando usar: POC, benchmark, “dá para fazer X?”, protótipo descartável.

spike/testcontainers-mysql-55-performance
spike/validar-archunitnet-custom-rules

Regras:

• Não mergear código experimental direto em staging
• Se a spike virar entrega: abrir feature/* ou refactor/* limpa com o que for manter
• Branch de spike pode ser abandonada/deletada sem merge

CI em spike: opcional; não bloquear recursos de homologação.

---

4. Fluxos completos

4.1 Desenvolvimento normal (happy path)

1. git fetch && git checkout staging && git pull
2. git checkout -b feature/comercial-novo-endpoint
3. Desenvolver + testes locais (.\scripts\test.ps1)
4. Push → abrir PR feature/* → staging
5. CI verde + review → merge staging
6. Deploy automático homolog
7. QA + E2E em staging
8. Quando lote aprovado: PR staging → main
9. Tag v* + deploy produção
10. (Opcional) merge main → staging se staging divergiu

4.2 Vários features em homologação

staging acumula merges até o release batch:

feature/A ──► staging ◄── feature/B
                  │
                  │ QA conjunto
                  ▼
               main (v1.5.0)

WIP limit sugerido: no máximo 3 features em validação simultânea em homolog. Acima disso, fila em branch até slot de QA.

4.3 Hotfix com staging em meio a release

staging: feature/A + feature/B (em QA)
main:    v1.4.0 (prod)

Incidente prod → hotfix/C from main
  → merge main (v1.4.1 deploy)
  → cherry-pick ou merge hotfix → staging
  → QA revalida feature/A e B + hotfix C
  → staging → main (v1.5.0 ou v1.4.2 conforme escopo)

Documentar no chamado se hotfix adiou release de features já em staging.

4.4 Promoção staging → main

Quem decide: product owner + tech lead (ou release owner da sprint).

Quando promover:

• QA sign-off em staging
• E2E/smoke verdes
• Sem chamados bloqueantes abertos para o lote
• Migrations testadas em homolog

Como promover:

1. PR staging → main (não merge direto)
2. Título: Release v1.5.0 — staging → main
3. Corpo: lista de PRs/features, chamados, notas de migration
4. Após merge: tag v1.5.0, deploy prod, release notes

Frequência sugerida: 1× por semana ou 2× por sprint — evitar staging “congelada” por semanas.

---

5. Gestão dentro da empresa

5.1 Papéis e responsabilidades

Papel	Responsabilidade
Desenvolvedor	Branch correta, testes locais, PR descrito, responder review
Revisor	Code review, checar testes de persistência, arquitetura
QA	Validar em homolog após merge em staging; registrar evidências
Release owner / Tech lead	Aprovar staging → main, tag, comunicar deploy
Suporte / Produto	Priorizar hotfix vs fix normal; aceitar janela de release

5.2 Integração com chamados (Linear, DevOps, etc.)

Todo PR deve referenciar o ID do chamado (ex.: 043447):

• Título: [043447] fix: es1 não atualiza após ajuste de estoque
• Branch: fix/043447-es1-saldo
• Release notes: agrupar por versão v1.5.0

5.3 Cerimônias sugeridas

Cerimônia	Frequência	Foco
Daily	Diária	Branches abertas, bloqueios, conflitos em staging
Staging review	2×/semana	O que está em homolog, o que promove a main
Release planning	Início sprint	Lote esperado para staging → main
Post-mortem hotfix	Após hotfix	Por que não pegou em CI/homolog; teste faltante

5.4 Comunicação de deploy

Merge em staging:

• Aviso no canal do time: “feature/X em homolog — URL, rotas, como testar”
• QA assume validação em até X dias (definir SLA interno, ex.: 2 dias úteis)

Merge staging → main:

• Release notes curtas (features, fixes, breaking changes)
• Aviso suporte antes de deploy prod (se impacto visível)

Hotfix:

• Aviso imediato produto + suporte
• Tag patch documentada

5.5 Branch protection (GitHub)

Configurar no repositório:

main:

• Require PR
• Require status checks: CI completo
• Require review (≥ 1)
• Restrict push (apenas bots/admins se necessário)
• Require linear history (opcional)

staging:

• Require PR
• Require status checks: architecture + unit + integration (8.0 + 5.5)
• Require review (≥ 1)
• No direct push

---

6. Quando criar, quebrar e abandonar branches

6.1 Quando criar nova branch

Situação	Branch
Novo chamado de feature	feature/* from staging
Bug encontrado em homolog/dev	fix/* from staging
Bug crítico em prod	hotfix/* from main
Reorganizar pastas/namespaces	refactor/* from staging
Só documentação ou CI	chore/* from staging
“Será que funciona?”	spike/* from staging (descartável)

Sempre: git pull em staging (ou main para hotfix) antes de criar.

6.2 Quando quebrar (split) uma branch

Dividir quando qualquer condição abaixo for verdadeira:

Sinal	Ação
PR > ~400 linhas úteis (excl. moves)	Dividir em 2+ PRs sequenciais
Branch aberta > 5 dias úteis	Rebase em staging; se muito grande, split
Dois chamados independentes na mesma branch	Split: um PR por chamado
Metade merged mentalmente, metade WIP	Commit WIP em branch filha ou stash; merge só o pronto
Conflitos constantes com staging	Rebase frequente ou split por área (Features/Comercial vs Features/Geral)
Refactor + feature na mesma branch	Separar: refactor/* primeiro, depois feature/*

Como quebrar na prática:

feature/comercial-grande
        │
        ├── feature/comercial-grande-parte1-refactor  → staging (merge 1)
        └── feature/comercial-grande-parte2-endpoint  → staging (merge 2, after 1)

Cada parte deve passar CI sozinha. Preferir merge sequencial (parte 1 antes de 2) quando há dependência.

Migrations / moves em massa:

• PR 1: refactor/moves-vertical-slice (só paths, zero regra nova)
• PR 2: feature/... (comportamento)

6.3 Quando não quebrar

• Mudanças indivisíveis (transação única entre contextos — ex.: fix 043447)
• PR pequeno (< 200 linhas) mesmo tocando vários arquivos
• Rename puro gerado por script (um PR atomizado)

6.4 Quando abandonar branch

• Spike concluída sem entrega
• Feature cancelada pelo produto
• Abordagem errada — documentar aprendizado no chamado e fechar PR

Deletar branch remota após fechar PR.

6.5 Conflitos com staging

Antes de merge do PR:

git fetch origin
git rebase origin/staging   # ou merge origin/staging, padrão do time
# rodar .\scripts\test.ps1
git push --force-with-lease  # se rebase

Nunca resolver conflito apenas localmente sem rerodar testes de integração.

---

7. CI/CD por etapa (referência — YAML futuro)

Detalhamento para quando .github/workflows/ for criado.

7.1 PR {temporária} → staging

Etapa	Comando / escopo
Build	dotnet build SGApi.sln -c Release
Architecture	dotnet test tests/SGApi.ArchitectureTests -c Debug
Unit	dotnet test tests/SGApi.UnitTests -c Debug
Integration 8.0	SGAPI_MYSQL_IMAGE=mysql:8.0
Integration 5.5	SGAPI_MYSQL_IMAGE=mysql:5.5

Path filters: ignorar PRs que só alteram docs/** sem impacto (opcional — architecture ainda pode rodar).

7.2 Merge em staging

Etapa	Escopo
E2E / smoke	Ambiente homolog
Security scan	Dependências, container
Deploy	Imagem :staging ou SHA
Migrations	BD homolog

Integração 8.0/5.5 já rodou no PR — repetir em merge staging se quiser belt-and-suspenders; não é obrigatório se PR foi recente.

7.3 PR staging → main

Etapa	Escopo
Validar último CI de staging	Ou rerun full pipeline
Tag	vMAJOR.MINOR.PATCH
Deploy prod	Imagem imutável por tag
Observability	Healthcheck /ping, alertas

---

8. Nomenclatura e commits

8.1 Branches

<tipo>/<area>-<descricao-kebab-case>

Tipos: feature, fix, hotfix, refactor, chore, spike.

Área alinhada a src/Features/: comercial, auth, geral, infra, ci.

8.2 Commits (recomendado)

Padrão convencional facilita release notes:

feat(comercial): adicionar endpoint ajuste estoque
fix(ajustes-estoque): transação compartilhada es1 e movimento
refactor(auth): migrar namespace para SGApi
chore(ci): adicionar workflow de integração

8.3 Títulos de PR

[043447] fix(comercial): es1 não atualiza após ajuste de estoque
feat(comercial): criar pedido de compra — POST pedidos-compras
refactor: migrar WSLinear.Consultas para SGApi.*
Release v1.5.0 — staging → main

---

9. Anti-padrões (proibidos)

Anti-padrão	Por quê
Push direto em staging ou main	Sem review, sem CI, sem rastreio
feature/* → main pulando staging	Sem homologação
Deixar staging sem sync após hotfix	Homolog ≠ prod
Branch viva > 2 semanas	Conflitos, integração tardia
Hotfix sem teste	Regressão em prod
Múltiplos chamados em um PR enorme	Review impossível, rollback difícil
Spike mergeada sem limpeza	Código experimental em homolog
Deploy prod de branch temporária	Só tags de main em prod

---

10. FAQ

Posso abrir PR de fix/* direto para main?
Não, exceto hotfix crítico via fluxo hotfix/*.

staging quebrou após merge — o que fazer?
Revert do merge problemático em staging (PR revert), ou hotfix fix/* priorizado. Não acumular “fixes empilhados” sem CI.

Dois devs na mesma subfeature?
Branch única compartilhada ou sub-branches curtas mergeadas na feature branch antes do PR staging.

Só mudei docs — preciso de integration test?
Não, se path filter no CI excluir; architecture tests em docs-only são opcionais.

Release só com chore/docs?
Pode promover staging → main com lote leve; tag patch mesmo assim.

Como versionar?
Semver: vMAJOR.MINOR.PATCH. Breaking API → MAJOR; features → MINOR; fix/hotfix → PATCH.

---

11. Checklists rápidos

Desenvolvedor — antes do PR para staging

• Branch atualizada com staging
• .\scripts\test.ps1 verde localmente
• Chamado linkado no PR
• Tabelas de persistência assertadas (se mutação)
• ADR/baseline atualizados (se cross-feature ou arquitetura)

QA — após merge em staging

• Rotas listadas no PR testadas
• SuperApp fluxo feliz + erro
• Smoke E2E (se aplicável)
• Sign-off registrado (comentário PR release ou ferramenta)

Release owner — staging → main

• QA sign-off completo
• Release notes redigidas
• Migrations revisadas
• Janela de deploy acordada
• Rollback plan (tag anterior v*)

Hotfix — pós merge main

• Tag patch criada
• Prod validado
• staging sincronizado
• Post-mortem agendado (se severidade alta)

---

12. Referências internas

• ADR 001 — Monólito modular
• ADR 002 — Dependências cross-feature
• ADR 003 — Estratégia de branches
• Estratégia de testes
• Testes arquiteturais
• Testes E2E
• DOCKER_BUILD_GUIDE.md
• scripts/test.ps1

---

Última atualização: documento alinhado à decisão de integração MySQL 8.0 + 5.5 em PRs para staging.