@polymorphism-tech/morph-spec 2.4.0 → 3.0.0

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

@@ -1,398 +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*
+# 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*