@polymorphism-tech/morph-spec 1.0.4 → 2.0.0

package/content/.azure/docs/branch-strategy.md

@@ -0,0 +1,398 @@
+# Estratégia de Branches - MORPH-SPEC
+
+> **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*