@polymorphism-tech/morph-spec 4.3.4 → 4.3.6

package/.morph/standards/core/git-branching-strategy.md

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

package/.morph/standards/core/git.md

@@ -0,0 +1,185 @@
+# Git Standards
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** git, commit, branch, version control, collaboration
+> **Load When:** always
+
+Version control and collaboration standards for MORPH-SPEC projects
+
+---
+
+## Commit Messages
+
+### Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Types
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Code style (formatting, no logic change)
+- `refactor`: Code refactoring (no feature/fix)
+- `test`: Adding/updating tests
+- `chore`: Build/tool/dependency updates
+- `perf`: Performance improvement
+
+### Examples
+
+```bash
+feat(auth): add JWT refresh token rotation
+
+Implemented automatic refresh token rotation on every token refresh
+to improve security. Old tokens are invalidated immediately.
+
+Closes #123
+```
+
+```bash
+fix(api): prevent SQL injection in search endpoint
+
+Sanitized user input before database query execution.
+Added parameterized queries for all search operations.
+```
+
+---
+
+## Branch Naming
+
+### Format
+
+```
+<type>/<issue-number>-<short-description>
+```
+
+### Types
+
+- `feature/` - New features
+- `bugfix/` - Bug fixes
+- `hotfix/` - Urgent production fixes
+- `refactor/` - Code refactoring
+- `docs/` - Documentation updates
+
+### Examples
+
+```bash
+feature/123-user-authentication
+bugfix/456-login-redirect
+hotfix/789-payment-gateway-timeout
+```
+
+---
+
+## Workflow
+
+### Feature Development
+
+```bash
+# 1. Create branch from main
+git checkout main
+git pull origin main
+git checkout -b feature/123-user-auth
+
+# 2. Make changes, commit often
+git add .
+git commit -m "feat(auth): add User entity"
+
+# 3. Push to remote
+git push -u origin feature/123-user-auth
+
+# 4. Create pull request
+# 5. After approval, squash merge to main
+```
+
+### Pull Request Standards
+
+- **Title**: Same format as commit messages
+- **Description**:
+  - Summary of changes
+  - Related issues
+  - Testing done
+  - Breaking changes (if any)
+- **Reviewers**: Minimum 1 approval required
+- **CI/CD**: All checks must pass
+
+---
+
+## Best Practices
+
+### DO
+
+✅ Commit early and often (small, focused commits)
+✅ Write descriptive commit messages
+✅ Pull before push to avoid conflicts
+✅ Use `.gitignore` to exclude build artifacts, secrets
+✅ Tag releases (`v1.0.0`, `v1.1.0`)
+
+### DON'T
+
+❌ Commit secrets (API keys, passwords)
+❌ Commit large binary files
+❌ Force push to shared branches
+❌ Commit directly to `main` (use PRs)
+❌ Use generic messages ("fix", "update")
+
+---
+
+## .gitignore Templates
+
+### .NET Projects
+
+```gitignore
+# Build results
+bin/
+obj/
+*.user
+*.suo
+
+# NuGet packages
+*.nupkg
+packages/
+
+# Environment files
+.env
+.env.local
+appsettings.Development.json
+
+# IDE
+.vs/
+.vscode/
+.idea/
+```
+
+### Node.js Projects
+
+```gitignore
+# Dependencies
+node_modules/
+npm-debug.log
+yarn-error.log
+
+# Build output
+dist/
+.next/
+out/
+
+# Environment
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*