GitHub profissional: PR, review, issues, Actions básico

# Fluxo para contribuir com open-source:

# 1. Fork no GitHub (botão Fork na interface)
# 2. Clone do SEU fork (não do original)
git clone git@github.com:SEU-USER/projeto.git
cd projeto

# 3. Adicionar o original como "upstream"
git remote add upstream git@github.com:DONO-ORIGINAL/projeto.git
git remote -v
# origin  git@github.com:SEU-USER/projeto.git (fetch)
# upstream git@github.com:DONO-ORIGINAL/projeto.git (fetch)

# 4. Manter fork atualizado com o original
git fetch upstream
git checkout main
git merge upstream/main     # ou: git rebase upstream/main

# 5. Criar branch para sua mudança
git checkout -b fix/bug-de-login

# 6. Push para SEU fork
git push origin fix/bug-de-login

# 7. Abrir PR no GitHub: seu fork → repositório original

# Template de PR (/github/PULL_REQUEST_TEMPLATE.md no repo)
## O que essa mudança faz?
Adiciona autenticação JWT na API. Substitui sessões em memória.

## Por quê?
Preparação para múltiplos servidores — sessões em memória não funcionam com load balancer.
Closes #89

## Como testar?
1. npm run dev
2. POST /auth/login com {"email": "test@test.com", "password": "123"}
3. Usar o token retornado no header Authorization: Bearer <token>
4. GET /profile deve retornar dados do usuário

## Checklist
- [x] Testes adicionados/atualizados
- [x] Documentação atualizada
- [ ] Migration necessária? Não

# Como dar review no GitHub:
# 1. Files Changed → ver diff completo
# 2. Click na linha → adicionar comentário inline
# 3. "Start a review" → acumula comentários antes de submeter
# 4. Submit review: Comment / Approve / Request Changes

# Tipos de comentário (boa prática nomear explicitamente):
# "nit: " — nitpick menor, pode ignorar ou não
# "suggestion: " — sugestão não-bloqueante
# "must: " — bloqueante, precisa resolver antes do merge
# "question: " — só pedindo explicação, não bloqueante

# Exemplos de comentários construtivos:
# ❌ "Isso está errado"
# ✅ "Esta query pode ter N+1 — que tal usar um JOIN aqui? [link para docs]"

# ❌ "Por que você fez assim?"
# ✅ "Tenho curiosidade sobre a escolha de X sobre Y — tem alguma razão específica?
#     Pensei que Y seria mais simples aqui."

# Ao receber review:
# - Responder cada comentário (mesmo com "feito" ou "concordo/discordo porque...")
# - Resolve conversation após resolver
# - Re-request review quando pronto

# Issues: rastrear bugs, features, tarefas
# Boas práticas:
# - Título descritivo: não "Bug login", sim "Login falha com email com +alias (ex: user+tag@mail.com)"
# - Reprodução mínima para bugs (OS, versão, passos exatos)
# - Expected vs Actual behavior
# - Labels para categorizar
# - Assign para responsável

# Labels úteis (criar no repo: Settings → Labels)
bug           # comportamento incorreto
enhancement   # nova funcionalidade
good first issue  # adequado para contribuintes novos
help wanted   # contribuições externas bem-vindas
breaking change  # muda API ou comportamento existente
needs-triage  # ainda não avaliado
blocked       # aguardando outra coisa

# Milestones: agrupar issues em um objetivo/release
# Settings → Milestones → New Milestone
# "v2.0 — autenticação multi-tenant" com due date
# Associar issues ao milestone → ver progresso

# Linking issues nos commits/PRs
git commit -m "fix: corrige login com email alias

Fixes #42"
# GitHub linkará automaticamente e fechará ao merge

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run lint

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test

  deploy:
    runs-on: ubuntu-latest
    needs: [lint, test]          # só roda se lint e test passaram
    if: github.ref == 'refs/heads/main'  # só na branch main
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
      - name: Deploy para produção
        env:
          DEPLOY_KEY: ${'$'}{{ secrets.DEPLOY_KEY }}  # segredo armazenado no repo
        run: ./scripts/deploy.sh

# Settings → Branches → Add branch protection rule
# Branch name pattern: main (ou usar glob: release/*)

# Configurações recomendadas para equipes:
✅ Require a pull request before merging
   ✅ Require approvals: 1 (ou 2 para times maiores)
   ✅ Dismiss stale pull request approvals when new commits are pushed
   ✅ Require review from Code Owners (se tiver .github/CODEOWNERS)

✅ Require status checks to pass before merging
   ✅ Require branches to be up to date before merging
   Status checks: lint, test (os jobs do CI)

✅ Require conversation resolution before merging

✅ Do not allow bypassing the above settings
   (mesmo admins precisam seguir as regras — importante!)

# CODEOWNERS: definir quem deve revisar arquivos específicos
# .github/CODEOWNERS
*.go          @time-backend
src/api/      @time-api
*.sql         @dba-team
docs/         @tech-writers