Estratégia de Branches Git — Modelo OneFlow Oficial

1. Fundamentação Conceitual e Origem (Adam Ruka, 2015)

O gerenciamento de código-fonte em projetos corporativos de grande porte exige um modelo de ramificação que equilibre simplicidade operacional, capacidade de auditoria e flexibilidade para conviver com múltiplos ritmos de trabalho.

No ecossistema do e-SUS AF, o desenvolvimento de software é organizado em três frentes complementares:

• Suporte N3: Triagem e diagnóstico avançado de incidentes complexos sem atuação em código de aplicação.
• Sustentação: Célula dedicada à resolução rápida de incidentes de produção via fluxo Kanban para defeitos de severidade Sev 1 (Hotfixes emergenciais) e Sev 2 (Bugfixes urgentes).
• Evolução: Linha contínua de entrega de valor operando no modelo Release Train (2+1), composto por 2 Sprints de Desenvolvimento (4 semanas) seguidas de 1 Sprint de Estabilização e Homologação (1 a 2 semanas).

Para orquestrar essas frentes sem atritos de versionamento, avaliou-se os modelos de mercado e adotou-se o OneFlow.

flowchart LR
    subgraph GitFlow["Git Flow Clássico (Legado Abandonado)"]
        GF1["2 Branches Perpétuas: main + develop"]
        GF2["Merges Duplos e Divergência Contínua"]
    end

    subgraph GitHubFlow["GitHub Flow Puro (Inadequado para e-SUS AF)"]
        GH1["1 Branch Perpétua: main"]
        GH2["Sem suporte a Code Freeze / Homologação Ministerial"]
    end

    subgraph OneFlow["OneFlow Oficial (e-SUS AF)"]
        OF1["1 Branch Perpétua Única: main"]
        OF2["Branches Temporárias: feature/*, release/*, hotfix/*"]
        OF3["Suporte Nativo a Estabilização e Hotfix sem Develop"]
    end

    GitFlow -.->|"Superado por"| OneFlow
    GitHubFlow -.->|"Superado por"| OneFlow

Por que abandonamos o Git Flow clássico?

O modelo Git Flow tradicional (criado por Vincent Driessen em 2010) foi amplamente utilizado na indústria, mas apresenta problemas estruturais crônicos:

1. Dualidade de Branches Perpétuas (main e develop): Manter duas branches infinitas exige sincronizações constantes e bidirecionais. A branch develop frequentemente acumula commits divergentes da main, resultando em "desvios históricos" (branch drift) difíceis de reconciliar.
2. Merges Duplos e Redundância: No Git Flow, o fechamento de uma release ou hotfix exige merges simultâneos tanto na main quanto na develop. Na prática, desenvolvedores esquecem um dos merges, gerando regressões silenciosas de bugs já corrigidos.
3. Poluição Histórica e Dificuldade de Rastreabilidade: O excesso de commits de merge ("merge bubbles") obscurece a linha do tempo do repositório, tornando comandos de auditoria como git bisect e git log lentos e complexos.

Por que o GitHub Flow puro não atende às necessidades do e-SUS AF?

O GitHub Flow puro baseia-se na premissa de Entrega Contínua (CD) onde qualquer feature mergeada na main é imediatamente implantada em produção. Embora elegante para microsserviços SaaS, esse modelo é inviável no e-SUS AF pelos seguintes motivos:

1. Exigência de Sprint de Estabilização & Homologação Negocial: Como software do Sistema Único de Saúde (SUS), cada versão maior ou menor passa por validação formal de negócio (Product Owner e analistas ministeriais) e bateria exaustiva de testes de regressão de QA.
2. Paralisação do Time em Caso de Code Freeze: No GitHub Flow puro, para congelar uma versão para testes de homologação, seria necessário congelar a própria branch main, paralisando o trabalho dos desenvolvedores de novas funcionalidades durante as 2 semanas da Sprint de Estabilização.

A Solução OneFlow

O OneFlow (Adam Ruka, 2015) resolve perfeitamente esse dilema:

• Mantém apenas UMA branch perpétua (main), eliminando completamente a complexidade da develop.
• Permite a abertura de Release Branches temporárias no momento do Code Freeze, permitindo que a equipe de QA e PO realize a homologação isolada enquanto a branch main permanece livre para receber Pull Requests do ciclo seguinte.
• Permite a abertura de Hotfix Branches temporárias diretamente a partir de tags de produção, possibilitando correções emergenciais rápidas sem poluir o histórico.

2. Tabela Comparativa Detalhada entre os Modelos Git

A tabela a seguir sumariza as diferenças arquiteturais e operacionais entre o Git Flow clássico, o GitHub Flow puro e a estratégia OneFlow oficial do e-SUS AF:

3. Diagrama do Ciclo de Vida OneFlow no e-SUS AF

O diagrama gitGraph abaixo ilustra o ciclo de vida completo de uma iteração no e-SUS AF, cobrindo o desenvolvimento de funcionalidades, a abertura de uma release na Sprint de Estabilização, o tratamento de um hotfix emergencial de produção pela Sustentação, a sincronização anti-regressão (cherry-pick) e o fechamento final da release com tags semânticas:

gitGraph
    commit id: "v1.0.0 (Prod)" tag: "v1.0.0"

    %% Sprint 1 e 2 de Dev: Feature 101
    branch feature/101-dispensacao
    checkout feature/101-dispensacao
    commit id: "feat: logica dispensacao"
    commit id: "test: testes e2e"
    checkout main
    merge feature/101-dispensacao id: "PR #101"

    %% Sprint 2 de Dev: Feature 102
    branch feature/102-relatorio
    checkout feature/102-relatorio
    commit id: "feat: relatorio analitico"
    checkout main
    merge feature/102-relatorio id: "PR #102"

    %% Fim da Sprint 2 de Dev: Code Freeze e Abertura da Release Branch
    branch release/v1.1.0
    checkout release/v1.1.0
    commit id: "fix: ajuste homologacao negocio"

    %% Incidente de Produção: Sustentação cria Hotfix a partir da tag v1.0.0
    checkout main
    branch hotfix/105-bloqueio-login
    checkout hotfix/105-bloqueio-login
    commit id: "fix: hotfix erro 500 login"

    %% Publicação do Hotfix na main com nova tag patch
    checkout main
    merge hotfix/105-bloqueio-login id: "Tag v1.0.1 (Prod)" tag: "v1.0.1"

    %% Sincronização Obrigatória (Anti-Regressão) via Cherry-pick na Release ativa
    checkout release/v1.1.0
    cherry-pick id: "fix: hotfix erro 500 login"
    commit id: "Sync hotfix v1.0.1"

    %% Fechamento da Release de Evolução pós-homologação (Merge na main com tag minor)
    checkout main
    merge release/v1.1.0 id: "Tag v1.1.0 (Prod)" tag: "v1.1.0"

Leitura Operacional do Diagrama

1. Estado Inicial: O projeto encontra-se em produção estável com a tag semântica v1.0.0.
2. Sprints de Desenvolvimento (Evolução): Os desenvolvedores criam branches feature/* a partir da main, realizam commits com testes e integram de volta na main via Pull Request aprovado com flag --no-ff.
3. Início da Estabilização (Code Freeze): O Líder Técnico bifurca a branch release/v1.1.0 a partir da main. A partir deste instante, a main fica liberada para receber PRs do ciclo seguinte, enquanto a release/v1.1.0 recebe apenas correções de homologação.
4. Incidente Crítico de Produção (Sustentação): Ocorre uma falha crítica de login em produção. A célula de Sustentação cria a branch hotfix/105-bloqueio-login a partir da tag v1.0.0, implementa a correção com testes e realiza o merge na main, gerando a tag de patch v1.0.1.
5. Regra de Sincronização Anti-Regressão: Como a branch release/v1.1.0 está ativa em homologação, o desenvolvedor da Sustentação executa obrigatoriamente um git cherry-pick do commit de correção para dentro da release/v1.1.0, impedindo que o futuro deploy da versão v1.1.0 reintroduza o bug.
6. Conclusão da Release: Aprovado o Definition of Done (DoD) de Release pelo PO e QA, a branch release/v1.1.0 é mergeada na main, recebe a tag v1.1.0 e é excluída.

4. Catálogo de Branches e Ciclo de Vida Operacional

Abaixo estão detalhadas as quatro categorias de branches do OneFlow no e-SUS AF, suas regras de governança e comandos passo a passo.

classDiagram
    class MainBranch {
        +Tipo: Perpétua Única
        +Protegida: Sim (CI/CD Obrigatório)
        +Origem: N/A
        +Destino: Produção Auditada
    }
    class FeatureBranch {
        +Tipo: Temporária
        +Origem: main
        +Destino: main (via PR)
        +Nomenclatura: feature/ID-descricao
    }
    class ReleaseBranch {
        +Tipo: Temporária
        +Origem: main (no Code Freeze)
        +Destino: main (com Tag Minor vX.Y.0)
        +Nomenclatura: release/vX.Y.0
    }
    class HotfixBranch {
        +Tipo: Temporária
        +Origem: Tag de Produção (vX.Y.Z)
        +Destino: main (Tag Patch) + cherry-pick release/*
        +Nomenclatura: hotfix/ID-descricao
    }
    MainBranch <|-- FeatureBranch : Bifurca e Mergeia
    MainBranch <|-- ReleaseBranch : Bifurca no Freeze e Mergeia com Tag
    MainBranch <|-- HotfixBranch : Bifurca da Tag e Mergeia com Patch

4.1. Branch Perpétua (main)

• Propósito: É a espinha dorsal do repositório. Contém a história oficial, estável e auditável de todas as versões do e-SUS AF. Toda tag de produção reside na main.
• Políticas de Proteção:
  • Pushes diretos bloqueados via permissões de repositório (GitLab / GitHub).
  • Merge permitido unicamente através de Pull Request com pelo menos 1 aprovação formal (Líder Técnico ou revisor designado).
  • Pipeline de CI/CD deve estar 100% verde (Lint, Testes Unitários e Testes E2E sem falhas).
  • O merge de PRs deve sempre gerar um commit de merge com flag --no-ff para preservar o registro histórico da revisão.

4.2. Branches de Funcionalidade (feature/<issue>-<descricao>)

• Finalidade: Desenvolvimento de novas Histórias de Usuário, melhorias funcionais ou débitos técnicos priorizados na Sprint de Evolução.
• Origem: Branch main (sempre atualizada com a última versão remota).
• Destino: Branch main (exclusivamente via Pull Request).
• Padrão de Nomenclatura: feature/<numero_issue>-<descricao_kebab_case>
  • Exemplo: feature/1215-manter-localizacao

Guia de Comandos Passo a Passo:

# 1. Atualizar a branch main local antes de iniciar
git checkout main
git pull origin main

# 2. Criar e alternar para a nova branch de feature
git checkout -b feature/1215-manter-localizacao

# 3. Realizar commits incrementais e atômicos durante o desenvolvimento
git add src/
git commit -m "feat(localizacao): adiciona validacao de CNES unico no cadastro"
git commit -m "test(localizacao): implementa testes e2e para fluxo basico e alternativos"

# 4. Sincronizar com a main remota antes de abrir PR (evita conflitos no PR)
git fetch origin
git rebase origin/main

# 5. Publicar a branch no repositório remoto
git push -u origin feature/1215-manter-localizacao

# 6. Abrir o Pull Request na interface web com destino para 'main'
# 7. Após o merge do PR pelo Tech Lead, limpar a branch local e remota:
git checkout main
git pull origin main
git branch -d feature/1215-manter-localizacao
git push origin --delete feature/1215-manter-localizacao

4.3. Branches de Release (release/vX.Y.0)

• Finalidade: Isolamento de versão no momento do Code Freeze (marco de transição entre a Sprint 2 de Desenvolvimento e a Sprint de Estabilização e Homologação).
• Origem: Branch main (no exato ponto do Code Freeze).
• Destino: Branch main (ao término da homologação), gerando a Tag Semântica Oficial (vX.Y.0).
• Padrão de Nomenclatura: release/vMAJOR.MINOR.0
  • Exemplo: release/v2.1.0
• Regra Estrita de Conteúdo: É expressamente proibido adicionar novas funcionalidades (features) em branches de release. Apenas correções de bugs identificados pelos testes de regressão de QA ou pela homologação negocial do PO são permitidas.

Guia de Comandos Passo a Passo:

# 1. Criação da Release Branch no Code Freeze (pelo Tech Lead / Release Manager)
git checkout main
git pull origin main
git checkout -b release/v2.1.0
git push -u origin release/v2.1.0

# 2. Durante a Estabilização: aplicação de correções cirúrgicas de homologação
git checkout release/v2.1.0
git add src/
git commit -m "fix(homolog): corrige formatacao de data no grid de dispensacao"
git push origin release/v2.1.0

# 3. Finalização da Release após aprovação formal do DoD pelo PO e QA
git checkout main
git pull origin main
git merge --no-ff release/v2.1.0 -m "chore(release): merge release v2.1.0"

# 4. Criação da Tag Semântica Anotada
git tag -a v2.1.0 -m "Release v2.1.0 homologada e pronta para producao"
git push origin main --tags

# 5. Exclusão da branch temporária de release
git branch -d release/v2.1.0
git push origin --delete release/v2.1.0

4.4. Branches de Hotfix (hotfix/<issue>-<descricao>)

• Finalidade: Correção emergencial e pontual de incidentes críticos de produção (Sev 1 ou Sev 2 urgente), executada pela célula de Sustentação.
• Origem: Tag de produção corrente na main (exemplo: tag v2.1.0).
• Destino: Branch main (com geração de nova Tag de Patch v2.1.1) E sincronização obrigatória com a release/* ativa caso haja uma Sprint de Estabilização em andamento.
• Padrão de Nomenclatura: hotfix/<numero_issue>-<descricao_kebab_case>
  • Exemplo: hotfix/1225-correcao-trava-dispensacao

Guia de Comandos Passo a Passo:

# 1. Criar a branch de hotfix a partir da tag oficial de produção
git checkout v2.1.0
git checkout -b hotfix/1225-correcao-trava-dispensacao

# 2. Implementação pontual da correção acompanhada de teste de regressão
git add src/ test/
git commit -m "fix(sustentacao): corrige condicao de corrida no estoque (#1225)"
git commit -m "test(sustentacao): adiciona teste e2e de concorrencia na dispensacao"

# 3. Merge na main com criação de Tag de Patch Semântica
git checkout main
git pull origin main
git merge --no-ff hotfix/1225-correcao-trava-dispensacao -m "fix(hotfix): merge hotfix v2.1.1 (#1225)"
git tag -a v2.1.1 -m "Hotfix emergencial v2.1.1 - Correcao de concorrencia de estoque (#1225)"
git push origin main --tags

# 4. Excluir a branch temporária de hotfix
git branch -d hotfix/1225-correcao-trava-dispensacao

5. Regra de Sincronização Obrigatória (Anti-Regressão)

Um dos maiores riscos em engenharia de software é a regressão silenciosa de incidentes: quando um bug crítico de produção é corrigido via Hotfix, mas uma versão futura em fase de homologação é publicada posteriormente sem conter essa correção, reintroduzindo a falha em produção.

No modelo OneFlow do e-SUS AF, a regra anti-regressão é estritamente mandatória:

flowchart TD
    HF_MERGE["Hotfix mergeado na main (Tag vX.Y.Z+1)"] --> CHECK_REL{"Existe branch release/* ativa em homologação?"}

    CHECK_REL -->|Sim| DO_CHERRY["1. Desenvolvedor da Sustentação executa Cherry-Pick na branch release/*"]
    DO_CHERRY --> RESOLVE_CONF{"Houve conflito no cherry-pick?"}
    RESOLVE_CONF -->|Sim| SOLVE["Dev resolve conflito junto com Líder Técnico"]
    RESOLVE_CONF -->|Não| PUSH_REL["2. Push na branch release/*"]
    SOLVE --> PUSH_REL
    PUSH_REL --> QA_NOTIF["3. Notifica time de QA para validação na esteira de homologação"]

    CHECK_REL -->|Não| NO_ACT["Nenhuma ação necessária: a main já contém o histórico completo"]

    style CHECK_REL fill:#fef3c7,stroke:#d97706,stroke-width:2px;
    style DO_CHERRY fill:#fee2e2,stroke:#dc2626,stroke-width:2px;
    style QA_NOTIF fill:#d1fae5,stroke:#059669,stroke-width:2px;

Procedimento Operacional de Cherry-Pick

Sempre que a célula de Sustentação finalizar um Hotfix e existir uma branch release/* em aberto na Sprint de Estabilização, o desenvolvedor responsável deve executar o seguinte procedimento:

# 1. Identificar o hash do commit do hotfix mergeado na main
git log -n 5 --oneline main
# Exemplo de saída:
# a1b2c3d fix(sustentacao): corrige condicao de corrida no estoque (#1225)

# 2. Alternar para a branch de release ativa e atualizar
git checkout release/v2.2.0
git pull origin release/v2.2.0

# 3. Aplicar o cherry-pick do commit específico do hotfix
git cherry-pick a1b2c3d

# 4. Caso surjam conflitos de código:
# - Abra os arquivos conflitantes, resolva as marcações e salve
# - git add <arquivos_resolvidos>
# - git cherry-pick --continue

# 5. Enviar a alteração sincronizada para a release remota
git push origin release/v2.2.0

# 6. Notificar o time de QA no canal da Sprint para validação do caso de teste

6. Padrão Semântico de Versionamento (SemVer) e Boas Práticas

Versionamento Semântico 2.0.0 (vMAJOR.MINOR.PATCH)

O e-SUS AF adota rigorosamente a especificação Semantic Versioning (SemVer 2.0.0):

$$\text{v}\mathbf{MAJOR}.\mathbf{MINOR}.\mathbf{PATCH}$$

flowchart LR
    subgraph SemVer["Estrutura da Tag: vMAJOR.MINOR.PATCH"]
        direction TB
        M["MAJOR (vX.0.0)"] -->|Quando| M_DESC["Quebra de compatibilidade, refatoração estrutural profunda ou migração de banco incompatível"]
        N["MINOR (v1.Y.0)"] -->|Quando| N_DESC["Lançamento oficial de ciclo de Evolução (2+1) com novas features homologadas"]
        P["PATCH (v1.1.Z)"] -->|Quando| P_DESC["Correções emergenciais de Sustentação em produção (Hotfixes Sev 1/2)"]
    end

• MAJOR (Versão Principal — vX.0.0):
  • Incrementado quando ocorrem mudanças arquiteturais incompatíveis com versões anteriores, reestruturação profunda de banco de dados que exige migração assistida, ou alterações drásticas de contratos de APIs públicas.
  • Ao incrementar MAJOR, reinicia-se MINOR e PATCH para 0 (exemplo: de v1.9.4 para v2.0.0).
• MINOR (Versão Secundária — v1.Y.0):
  • Incrementado ao término de cada ciclo de Evolução (Release Train 2+1). Adiciona novas funcionalidades, relatórios, telas e integrações de forma retrocompatível.
  • Ao incrementar MINOR, reinicia-se PATCH para 0 (exemplo: de v2.1.2 para v2.2.0).
• PATCH (Versão de Correção — v1.1.Z):
  • Incrementado a cada Hotfix publicado pela Sustentação para corrigir falhas de produção sem adicionar funcionalidades novas (exemplo: de v2.2.0 para v2.2.1).

Boas Práticas de Commit (Conventional Commits)

Todas as mensagens de commit no e-SUS AF devem aderir ao padrão Conventional Commits, estruturado no formato:

<tipo>(<escopo opcional>): <descrição no imperativo em português>

Tabela de Tipos de Commit Padronizados:

Padrão de Nomenclatura e Governança de Pull Requests

Para assegurar rastreabilidade total entre as tarefas de gestão (Jira / GitLab Issues) e o histórico de código, todo Pull Request deve seguir a convenção de título:

[TIPO] Descrição concisa e objetiva (#ID_ISSUE)

Exemplos de Títulos de PR:

• [FEAT] Implementa emissão de comprovante de dispensação em PDF (#1215)
• [FIX] Corrige condição de corrida no bloqueio de estoque concorrente (#1225)
• [REFACTOR] Reestrutura camada de repositório de usuários (#1230)

Checklist Obrigatório no Corpo do PR:

Todo PR aberto deve preencher o template padrão de submissão:

## Contexto e Motivação
Explique de forma clara o problema que este PR resolve ou a funcionalidade que implementa.
Link da Issue/Card: #1215

## Tipo de Alteração
- [x] Nova funcionalidade (feat)
- [ ] Correção de bug (fix)
- [ ] Refatoração de código (refactor)
- [ ] Ajuste de documentação (docs)

## Evidências de Testes
- [x] Testes unitários implementados e passando localmente.
- [x] Testes E2E cobrindo fluxo básico e fluxos alternativos implementados.
- [x] Pipeline de CI 100% verde.

## Verificação de Contratos
- [x] Nenhuma quebra de retrocompatibilidade de API.
- [x] Migração de banco de dados idempotente e reversível (se aplicável).

Estrutura Monorepo e Compatibilidade Front/Back

O repositório do e-SUS AF adota a arquitetura de Monorepo, mantendo os módulos de Frontend e Backend em um único repositório versionado pela branch main.

Essa decisão garante:

1. Sincronia Atômica de Contratos: Quando uma nova funcionalidade exige alteração em um endpoint de API e na interface de usuário, as duas alterações são comitadas e revisadas no mesmo Pull Request, eliminando discrepâncias de versão entre cliente e servidor.
2. Pipelines Integradas de Teste: A esteira de CI executa testes de ponta a ponta (End-to-End) sobre a aplicação completa em cada PR antes do merge.
3. Versionamento Unificado: Uma única tag semântica (ex.: v2.1.0) identifica univocamente o estado exato de todo o sistema entregue em produção.