Git Workflow & Branch Policies

📋 Visão Geral

Este documento define as políticas de branches e o workflow Git para o projeto Audissey, garantindo qualidade, rastreabilidade e estabilidade em produção.

🌳 Estrutura de Branches

Main Branch (`main`)

Propósito: Código em produção
Estado: Sempre estável e deployável
Deploy: Automático para Azure App Services (Production)
Proteção: ✅ Branch protegida

Development Branch (`dev`)

Propósito: Integração de features em desenvolvimento
Estado: Deve estar sempre funcional (testes passando)
Deploy: Automático para ambiente de staging (quando configurado)
Proteção: ⚠️ Recomendado proteger

Feature Branches (`feature/*`)

Propósito: Desenvolvimento de novas funcionalidades
Origem: Criadas a partir de dev
Destino: Merge via PR para dev
Naming: feature/nome-da-feature
Exemplos:
- feature/podcast-player
- feature/radio-epg-view
- feature/user-favorites

Bugfix Branches (`bugfix/*`)

Propósito: Correção de bugs não urgentes
Origem: Criadas a partir de dev
Destino: Merge via PR para dev
Naming: bugfix/descricao-do-bug
Exemplos:
- bugfix/stream-url-validation
- bugfix/podcast-sync-race-condition

Hotfix Branches (`hotfix/*`)

Propósito: Correções urgentes em produção
Origem: Criadas a partir de main
Destino: Merge via PR para main E dev
Naming: hotfix/descricao-urgente
Exemplos:
- hotfix/api-authentication-bypass
- hotfix/database-connection-leak

🔒 Políticas de Proteção

Branch `main` - Regras Obrigatórias

1. Pull Requests Obrigatórios

✅ Todos os commits devem ser via Pull Request
❌ Push direto bloqueado
✅ Squash merge recomendado para histórico limpo

2. Reviewers

Mínimo: 1 aprovação obrigatória
Recomendado: 2 aprovações para mudanças críticas
❌ Auto-merge do autor bloqueado

3. Build & Tests

✅ Pipeline CI deve passar (lint + testes)
✅ Build bem-sucedido obrigatório
❌ Merge bloqueado se testes falharem

4. Merge Strategy

Recomendado: Squash and merge
Benefício: Histórico limpo com 1 commit por feature

Formato do commit:

feat: implementar player de podcasts (#123)

- Adicionar controles de reprodução
- Implementar playlist
- Testes E2E completos

Branch `dev` - Regras Recomendadas

1. Pull Requests

✅ Recomendado (mas não obrigatório inicialmente)
✅ Code review fortemente encorajado

2. Build Status

✅ Pipeline deve passar antes do merge
⚠️ Avisos permitidos, erros não

🔄 Workflow de Desenvolvimento

1️⃣ Criar Feature Branch

# Garantir que está atualizado
git checkout dev
git pull origin dev

# Criar nova feature
git checkout -b feature/minha-feature

2️⃣ Desenvolver Feature

# Fazer commits frequentes e descritivos
git add .
git commit -m "feat: adicionar endpoint de favoritos"

# Push para remoto
git push -u origin feature/minha-feature

3️⃣ Criar Pull Request

Via Azure DevOps:

Acessar Repos → Pull Requests
Click "New pull request"
Source: feature/minha-feature
Target: dev
Preencher:
- Título: Claro e descritivo
- Descrição: O que foi feito e por quê
- Work Items: Associar tasks/stories
- Reviewers: Adicionar revisores

Template de PR:

## 📝 Descrição

Implementação do sistema de favoritos para podcasts e rádios.

## 🎯 Mudanças

- Adicionar endpoints GET/POST /api/favorites
- Criar schema Favorite no MongoDB
- Implementar autenticação JWT
- Testes unitários e E2E

## ✅ Checklist

- [x] Testes passando
- [x] Documentação atualizada
- [x] Breaking changes documentados
- [x] Performance verificada

## 🔗 Links

- Work Item: #1234
- Design: [Figma Link]

4️⃣ Code Review

O que verificar:

✅ Código limpo e legível
✅ Testes adequados
✅ Sem código comentado
✅ Sem secrets/credentials
✅ Performance aceitável
✅ Documentação atualizada

5️⃣ Merge para Dev

# Após aprovação
# Squash merge via Azure DevOps UI
# Deletar feature branch após merge

6️⃣ Release para Produção

# Criar PR de dev → main
# Título: "Release v1.2.0 - [data]"
# Incluir changelog completo
# Aguardar aprovação de reviewers
# Merge para main dispara deploy automático

📊 Configuração Azure DevOps

Passo 1: Proteger Branch Main

Acessar: Repos → Branches
Click nos ... da branch main
Selecionar Branch policies
Configurar:

Require a minimum number of reviewers:
- ✅ Enable
- Minimum: 1
- ✅ Allow requestors to approve their own changes: ❌ Desabilitar
- ✅ Prohibit the most recent pusher: ✅ Habilitar
- ✅ Reset votes when source branch is updated: ✅ Habilitar
Check for linked work items:
- ✅ Required (ou Optional)
Check for comment resolution:
- ✅ Required
Limit merge types:
- ✅ Squash merge only
Build validation:
- ✅ Add build policy
- Pipeline: Backend CI - API & Worker
- Trigger: Automatic
- Policy requirement: Required

Passo 2: Configurar Branch Dev (Opcional)

Repetir processo acima com regras mais relaxadas:

Reviewers: Optional
Build validation: Required
Merge types: All allowed

Passo 3: Configurar Default Branch

Acessar: Project Settings → Repositories
Selecionar repositório Audissey
Default branch: dev
Save

🚀 Deploy Automático

CI/CD Pipeline Triggers

# azure-pipelines.yml
trigger:
  branches:
    include:
      - main # Produção
      - dev # Staging (quando configurado)
      - feature/* # CI apenas (sem deploy)

pr:
  branches:
    include:
      - main
      - dev

Comportamento:

Push para main → Deploy automático para produção
Push para dev → CI + Deploy para staging (futuro)
PR para main/dev → CI + validação (sem deploy)
Feature branches → CI local apenas

📜 Conventional Commits

Formato

<type>(<scope>): <subject>

<body>

<footer>

Types

feat: Nova funcionalidade
fix: Correção de bug
docs: Apenas documentação
style: Formatação (sem mudança de código)
refactor: Refatoração sem mudança de comportamento
perf: Melhoria de performance
test: Adicionar/corrigir testes
chore: Tarefas de build, CI, dependências
ci: Mudanças no CI/CD

Exemplos

feat(api): adicionar endpoint de busca unificada

Implementa endpoint GET /api/search que busca em podcasts,
episódios e rádios simultaneamente.

Closes #456

---

fix(worker): corrigir race condition no sync de episódios

O worker estava criando episódios duplicados quando múltiplos
jobs rodavam em paralelo.

Fixes #789

---

docs(setup): atualizar guia de instalação do Azure

Adicionar instruções para Key Vault e Managed Identity.

---

perf(api): otimizar query de rádios por gênero

Reduz tempo de resposta de 500ms para 50ms usando índice composto.

Closes #234

🔍 Histórico Limpo

Squash Merge Benefits

Antes (sem squash):

* feat: adicionar favoritos
* fix: typo
* refactor: rename variable
* fix: lint errors
* update tests
* fix: more tests

Depois (com squash):

* feat: adicionar sistema de favoritos (#123)

Rebase vs Merge

Feature → Dev: Squash merge ✅
Dev → Main: Squash merge ✅
Hotfix → Main: Merge commit (para preservar urgência)

🆘 Troubleshooting

"Cannot push to protected branch"

✅ Solução: Criar Pull Request em vez de push direto

# Criar feature branch
git checkout -b feature/minha-mudanca

# Fazer mudanças e push
git push -u origin feature/minha-mudanca

# Criar PR via Azure DevOps UI

"Build validation failed"

✅ Solução: Corrigir erros antes do merge

# Rodar testes localmente
npm run lint
npm run test
npm run build

# Corrigir erros e fazer novo commit
git add .
git commit -m "fix: corrigir erros de testes"
git push

"Conflicts detected"

✅ Solução: Atualizar branch com dev

git checkout feature/minha-feature
git fetch origin
git rebase origin/dev

# Resolver conflitos
# git add <arquivos-resolvidos>
# git rebase --continue

git push --force-with-lease

📚 Recursos

✅ Checklist de Setup

Branch dev criada
Branch dev publicada
Branch policies configuradas em main
Build validation ativada
Default branch definido como dev
Team notificado sobre workflow
Documentação compartilhada

🪝 Git Hooks (Husky)

O projeto usa Husky + lint-staged para correr validações automáticas antes de commit e push, evitando erros nas pipelines CI/CD.

Setup (automático)

Após npm install, o Husky inicializa-se automaticamente via script prepare.

Pre-commit — Lint dos ficheiros staged

Corre eslint --fix e prettier --write sobre os ficheiros que estão no stage:

Glob	Comandos
`*.{ts,js,mjs,cjs}`	`eslint --fix`, `prettier --write`
`*.{html,css,scss,json,md,yml,yaml}`	`prettier --write`

Configuração em package.json → chave lint-staged.

Pre-push — Testes + Build (affected only)

Corre testes e build apenas para os projetos com alterações face a origin/dev:

App	Targets
api	`test`, `build`
worker	`test`, `build`
admin-portal	`lint`, `build`

Se nenhum projeto teve alterações, os checks são skipped.

Antes destes, corre os testes de scripts da Backend CI, se o push também os fizer correr no CI: ver Testes dos scripts no CI.

Bypass (emergência)

# Bypass pre-commit
git commit --no-verify -m "hotfix: urgent"

# Bypass pre-push
git push --no-verify

⚠️ Usar --no-verify apenas em emergências — as pipelines CI/CD continuam a validar.

Última atualização: 17 de julho de 2025
Mantido por: Equipe Audissey

Git Workflow & Políticas