# Git Branching Strategy

> **Scope:** universal
> **Layer:** 0
> **Keywords:** git, branch, workflow, pr, pull request, merge, staging, production, feature branch
> **Load When:** always

> **Git Flow simplificado para one-person business**

---

## 🌳 Estrutura de Branches

```
main/master (produção)
  ↑
  │ PR (com aprovação)
  │
staging (homologação)
  ↑
  │ PR (automático merge)
  │
feature/* (desenvolvimento)
```

### **Branches Principais**

| Branch | Propósito | Deploy | Aprovação |
|--------|-----------|--------|-----------|
| **`main`** ou **`master`** | Produção | Container Apps (always-on) | ✅ Obrigatória |
| **`staging`** | Homologação/QA | Container Apps (scale-to-zero) | ❌ Nenhuma |

### **Branches Temporárias**

| Padrão | Exemplo | Propósito |
|--------|---------|-----------|
| `feature/*` | `feature/add-payments` | Nova funcionalidade |
| `bugfix/*` | `bugfix/fix-login` | Correção de bug |
| `hotfix/*` | `hotfix/critical-security` | Correção urgente em prod |

---

## 🔄 Workflow Completo

### 1. Nova Feature

```bash
# Atualizar staging
git checkout staging
git pull origin staging

# Criar feature branch
git checkout -b feature/pagamentos-asaas

# Desenvolver localmente
# ... code, test, commit ...

# Push
git push origin feature/pagamentos-asaas

# Criar PR para staging
```

**Azure DevOps**:
1. **Repos** → **Pull Requests** → **New**
2. Source: `feature/pagamentos-asaas`
3. Target: `staging`
4. Title: "feat: integração com Asaas para pagamentos recorrentes"
5. Description: Detalhar mudanças
6. **Create**
7. **Approve** (você mesmo) e **Complete**

**Resultado**: Pipeline staging triggado automaticamente

---

### 2. Bug Fix

```bash
# Partir de staging
git checkout staging
git pull origin staging

# Criar bugfix branch
git checkout -b bugfix/corrigir-calculo-total

# Corrigir + testar
git add .
git commit -m "fix: corrige cálculo de total no carrinho"

# Push e PR para staging
git push origin bugfix/corrigir-calculo-total
```

---

### 3. Hotfix (Produção)

```bash
# Partir de main (produção)
git checkout main
git pull origin main

# Criar hotfix branch
git checkout -b hotfix/vulnerabilidade-critica

# Corrigir urgentemente
git add .
git commit -m "fix: corrige vulnerabilidade SQL injection"

# Push
git push origin hotfix/vulnerabilidade-critica

# Criar 2 PRs:
# 1. hotfix → main (deploy imediato)
# 2. hotfix → staging (manter ambientes sincronizados)
```

**Atenção**: Hotfix é para emergências! Use com moderação.

---

### 4. Release (Staging → Produção)

```bash
# Quando staging estiver estável e testado

# Criar PR no Azure DevOps:
# Source: staging
# Target: main

# Self-review checklist:
# - [ ] Funcionalidades testadas em staging
# - [ ] Performance OK
# - [ ] Sem erros nos logs
# - [ ] Migrations aplicadas
# - [ ] Documentação atualizada

# Approve e Complete
# Pipeline prod triggará
# ⏸️ Approval gate aparecerá
# Aprovar após validar deployment summary
```

---

## ⚙️ Configuração Azure DevOps

### Branch Policies (Staging)

**Repos** → **Branches** → `staging` → **Branch policies**:

```
✅ Require a minimum number of reviewers: 0
   (você pode fazer self-merge)

✅ Check for linked work items: Recommended
   (boa prática para rastreabilidade)

✅ Check for comment resolution: All
   (resolver comentários antes de merge)

✅ Build validation:
   - Pipeline: staging-pipeline
   - Trigger: Automatic
   - Policy requirement: Required
```

### Branch Policies (Main)

**Repos** → **Branches** → `main` → **Branch policies**:

```
✅ Require a minimum number of reviewers: 0
   (você faz self-review com approval gate no pipeline)

✅ Check for linked work items: Required
   (obrigatório para rastreabilidade)

✅ Check for comment resolution: All

✅ Build validation:
   - Pipeline: prod-pipeline
   - Trigger: Automatic
   - Policy requirement: Required

❌ Limit merge types:
   ✅ Squash merge only (recomendado)
   (mantém histórico limpo)
```

---

## 🎯 Boas Práticas

### Commits

```bash
# Use Conventional Commits
feat: adiciona integração com Asaas
fix: corrige cálculo de desconto
docs: atualiza README com instruções de deploy
refactor: simplifica lógica de autenticação
test: adiciona testes para carrinho de compras
chore: atualiza dependências do projeto

# Seja descritivo no body (se necessário)
git commit -m "feat: integração Asaas" -m "
- Adiciona AsaasClient para chamadas API
- Implementa webhook para notificações
- Cria tabela Subscriptions para assinaturas
- Adiciona testes de integração
"
```

### Feature Branches

```bash
# ✅ Bom
feature/add-asaas-integration
feature/user-dashboard
bugfix/fix-login-redirect

# ❌ Ruim
my-changes
temp
test
wip
```

### Merge vs Squash vs Rebase

**Recomendação para one-person business**: **Squash merge**

```
# Vantagens squash:
- Histórico limpo em main/staging
- Cada merge = 1 commit = 1 feature
- Fácil reverter feature inteira
- Fácil ler changelog

# Configurar no Azure DevOps:
Branch Policies → Limit merge types → Squash merge only
```

---

## 📊 Visualização do Fluxo

```
┌─────────────────────────────────────────────────────────┐
│  Developer Local                                        │
│                                                         │
│  feature/pagamentos-asaas                               │
│    │                                                    │
│    ├─ commit: adiciona AsaasClient                     │
│    ├─ commit: implementa webhook                       │
│    └─ commit: adiciona testes                          │
└──────────────────────│──────────────────────────────────┘
                       │
                       │ git push
                       │ + PR para staging
                       ↓
┌─────────────────────────────────────────────────────────┐
│  Staging Branch                                         │
│                                                         │
│  Squash merge                                           │
│    └─ feat: integração completa com Asaas             │
│                                                         │
│  Pipeline staging-pipeline triggado                     │
│    └─ Deploy automático para staging                   │
└──────────────────────│──────────────────────────────────┘
                       │
                       │ Testes manuais OK
                       │ PR staging → main
                       ↓
┌─────────────────────────────────────────────────────────┐
│  Main Branch (Produção)                                 │
│                                                         │
│  Squash merge                                           │
│    └─ feat: integração completa com Asaas             │
│                                                         │
│  Pipeline prod-pipeline triggado                        │
│    ├─ Build & Security Scan                            │
│    ├─ ⏸️ Approval gate (você aprova)                   │
│    └─ Deploy para produção                             │
└─────────────────────────────────────────────────────────┘
```

---

## 🆘 Cenários Comuns

### Conflito de Merge

```bash
# Atualizar feature branch com staging
git checkout feature/minha-feature
git fetch origin
git merge origin/staging

# Resolver conflitos manualmente
# Editar arquivos, escolher versão correta

git add .
git commit -m "merge: resolve conflitos com staging"
git push origin feature/minha-feature
```

### Reverter um Merge

```bash
# Se merge em staging deu problema
git checkout staging
git revert -m 1 <commit-hash-do-merge>
git push origin staging

# Pipeline triggará e deployará versão sem a feature
```

### Sincronizar Branch Desatualizada

```bash
# Sua feature ficou muito desatualizada
git checkout feature/antiga
git fetch origin
git merge origin/staging

# Ou, se preferir histórico limpo (rebase)
git rebase origin/staging

# Se houver conflitos, resolve e continua
git rebase --continue

git push origin feature/antiga --force-with-lease
```

### Deletar Branch Remota

```bash
# Após merge, deletar feature branch
git push origin --delete feature/minha-feature

# Deletar local também
git branch -d feature/minha-feature
```

---

## 📅 Cadência Recomendada

### Para One-Person Business

| Atividade | Frequência | Descrição |
|-----------|------------|-----------|
| **Commits** | Várias vezes/dia | Commits pequenos e frequentes |
| **Push** | 1-2x/dia | Push ao final do dia ou feature completa |
| **PR → Staging** | 1-3x/semana | Quando feature está funcional |
| **Deploy Staging** | Automático | Após merge no staging |
| **PR → Prod** | 1x/semana ou quinzenal | Quando staging está estável |
| **Deploy Prod** | Conforme necessário | Após aprovação manual |

**Dica**: Não acumule muitas features antes de fazer release. Releases pequenos e frequentes são mais seguros.

---

## ✅ Checklist de PR

### Antes de Criar PR

- [ ] Código testado localmente
- [ ] Unit tests passando (`dotnet test`)
- [ ] Sem warnings de compilação
- [ ] Código formatado/lint OK
- [ ] Commits com mensagens descritivas
- [ ] Branch atualizada com target (staging ou main)

### Ao Criar PR

- [ ] Título descritivo (feat/fix/docs/etc)
- [ ] Descrição clara do que mudou
- [ ] Linkar work item se houver
- [ ] Adicionar screenshots se for UI

### Antes de Aprovar (Self-Review)

- [ ] Revisar diff completo
- [ ] Verificar se não commitou secrets/senhas
- [ ] Verificar se não tem console.log/debug temporário
- [ ] Pipeline de build passou
- [ ] Sem conflitos

---

## 📚 Referências

- [Git Flow](https://nvie.com/posts/a-successful-git-branching-model/)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Azure Repos Branch Policies](https://learn.microsoft.com/azure/devops/repos/git/branch-policies)

---

*MORPH-SPEC by Polymorphism Tech*
