​
Git Workflow — Meu PACS Cloud

Este projeto segue Git Flow simplificado: duas branches permanentes (main e develop) e branches temporárias por feature/fix. O objetivo é separar o que está em desenvolvimento do que está em produção, com rastreabilidade clara de cada release.

​
1. Filosofia

maindevelop
PapelVersão estável — última release em produçãoVersão de trabalho — integração contínua de novas features
Quem mexeNinguém direto — só via PR de developNinguém direto — só via PR de branches temporárias
Quando atualizaEm releases (marcos estáveis)Diariamente
DeployProduçãoHomolog
Regra de ouro: nunca commitar direto em main nem em develop. Todo trabalho nasce em uma branch temporária, vira um PR, é revisado, e só então entra.

​
2. Branches permanentes

​
main

Contém a versão estável em produção. Cada commit em main é um release — um ponto consistente onde tudo funciona end-to-end. Recebe apenas PRs de develop, geralmente em lotes coerentes (ex.: “sistema de laudos completo”, “viewer + autenticação OHIF”).

​
develop

Contém o trabalho em andamento. Recebe PRs de branches temporárias conforme features/fixes são finalizados. Deve estar sempre em estado rodável — testes básicos passando, sem quebrar funcionalidades existentes. Serve de base para cortar novas branches e para deploy em homolog.

​
3. Branches temporárias

​
Convenção de nomes

<tipo>/<descrição-curta-em-kebab-case>
PrefixoUsoExemplo
feat/Nova funcionalidadefeat/rbac-laudos
fix/Correção de bugfix/navbar-preview-overlap
infra/Docker, CI, deploy, configsinfra/nginx-cors-proxy
docs/Só documentaçãodocs/runbook-migration
refactor/Refatoração sem mudança de comportamentorefactor/report-controller
Escreva a descrição em inglês ou português consistente com o projeto — aqui usamos português, mas mantenha as palavras técnicas (ex.: docker, webhook, jwt) em inglês.

​
Ciclo de vida

Branches temporárias são curtas — idealmente horas a poucos dias. Quanto mais tempo uma branch fica aberta, mais difícil o merge e maior o risco de conflito. Se o escopo crescer, divida em várias branches menores. Depois do merge, a branch pode ser deletada (local e remoto).

​
4. Fluxo: adicionar uma nova feature

# 1. Garanta que develop está atualizado
git checkout develop
git pull origin develop

# 2. Crie a branch a partir de develop
git checkout -b feat/nome-da-feature

# 3. Trabalhe — commits pequenos e focados
git add <arquivos-específicos>
git commit -m "Feat: descrição do que mudou"

# 4. Push da branch para o remoto
git push origin feat/nome-da-feature

# 5. Abra um PR: feat/nome-da-feature → develop
#    Título descritivo, descrição com contexto, test plan
gh pr create --base develop --title "Feat: ..." --body "..."

# 6. Após revisão e merge, delete a branch
git checkout develop
git pull origin develop
git branch -d feat/nome-da-feature
git push origin --delete feat/nome-da-feature

​
Durante o trabalho

  • Commits frequentes e pequenos — mais fácil de revisar e reverter
  • Se develop avançou enquanto você trabalhava, rebase na sua branch: 
    git fetch origin
git rebase origin/develop
    Resolva conflitos, rode testes, dê push forçado (--force-with-lease) só na sua branch (nunca em main/develop)

​
5. Fluxo: corrigir um bug

Mesmo padrão da feature, com prefixo fix/: 
git checkout develop && git pull
git checkout -b fix/descricao-do-bug
# ... corrige, testa ...
git commit -m "Fix: descrição do problema e da correção"
git push origin fix/descricao-do-bug
# PR → develop
Bug crítico em produção (raro): branch hotfix/ a partir de main, PR direto para main e também para develop (para não perder o fix no trunk). 
git checkout main && git pull
git checkout -b hotfix/nome
# ... corrige ...
git push origin hotfix/nome
# PR → main (emergencial)
# Depois, merge também em develop ou cherry-pick

​
6. Padrão de mensagens de commit

Tipo: descrição curta e imperativa
[linha em branco]
Detalhes se necessário (opcional):
- o que mudou
- por que mudou
- limitações conhecidas
Tipos usados:
TipoQuando
Feat:Nova funcionalidade
Fix:Correção de bug
Docs:Só documentação
Refactor:Refatoração sem mudança de comportamento
Infra:Docker, CI, deploy, configs
Test:Só testes
Chore:Manutenção (bump de dependência, etc.)
Bons exemplos: 
Feat: RBAC — somente doutores podem criar e editar laudos (P3)
Fix: drawer de preview de laudo abaixo da navbar na tela de estudos
Docs: adiciona pacs_queue na tabela de serviços Docker (seção 3)
Infra: configura CORS proxy Nginx para autenticação OHIF
Evite:
  • wip, fix stuff, updates — mensagens vagas
  • Commits gigantes com 10 arquivos e título genérico
  • Commits misturando tipos (ex.: feat + docs + refactor no mesmo)

​
7. Release: PR develop → main

Quando develop acumulou um conjunto coerente de features/fixes estáveis e testados, é hora de promover para main. Checklist antes de abrir o PR:
  1. Tudo em develop está pushado (sem commits locais pendentes)
  2. Deploy em homolog rodando a versão de develop sem erros
  3. Fluxos críticos validados em homolog:
    • Login, logout, refresh de JWT
    • Ingestão DICOM (estudo chega, thumbnail gerado, série indexada)
    • Viewer OHIF abre com token temporário
    • Fluxo de laudos: rascunho → finalizar → corrigir → exportar PDF
    • RBAC: cada role acessa só o que deve
  4. Migrations rodando sem erros no ambiente de homolog
  5. Documentação alinhada (README, ARCHITECTURE, ONBOARDING, RUNNING)
Abrir o PR: 
git checkout develop && git pull
gh pr create --base main --title "Release: <descrição do marco>" --body "$(cat <<'EOF'
## Summary
Resumo do que entra nesta release — bullets do que mudou desde a última.

## Validação
- [x] Deploy em homolog rodando
- [x] Fluxos críticos testados
- [x] Documentação alinhada

## Commits
(preenchido automaticamente pelo gh)
EOF
)"
Depois do merge em main, considere taggear a release: 
git checkout main && git pull
git tag -a v1.2.0 -m "Release v1.2.0 — sistema de laudos completo"
git push origin v1.2.0

​
8. Boas práticas

✅ Faça
  • Commits pequenos, focados, com mensagem descritiva
  • Rebase em develop antes de abrir PR (mantém histórico linear)
  • Revise o diff antes de pushar (git diff --cached)
  • Teste localmente antes do push
  • Delete branches temporárias após merge
❌ Evite
  • git push --force em main/develop (pode apagar trabalho alheio)
  • --no-verify para pular hooks (eles existem por motivo)
  • Misturar muitas mudanças não relacionadas no mesmo commit
  • Commits com segredos (.env, tokens, credenciais)
  • Merge de develop para a sua branch pra “atualizar” — use rebase

​
9. Comandos de referência rápida

# Ver estado atual
git status
git log --oneline -10
git branch -a                    # todas as branches (local + remoto)

# Atualizar develop local
git checkout develop && git pull origin develop

# Criar branch nova
git checkout -b feat/nome

# Rebase na sua branch (atualiza com develop)
git fetch origin
git rebase origin/develop
# (resolva conflitos)
git push --force-with-lease origin feat/nome

# Ver diff antes de commitar
git diff                         # mudanças não staged
git diff --cached                # mudanças staged

# Desfazer
git restore <arquivo>            # descarta mudanças não staged
git reset HEAD <arquivo>         # tira do staging (mantém mudanças)
git reset --soft HEAD~1          # desfaz último commit, mantém mudanças

# Limpar branches locais já mergeadas
git branch --merged develop | grep -v develop | xargs git branch -d

​
10. Quando fugir do fluxo

Git Flow funciona pra times pequenos com releases programadas — é o nosso caso hoje. Se o projeto crescer para:
  • Múltiplos devs em features paralelas independentes — vale olhar trunk-based development + feature flags
  • Deploys múltiplos por dia — Git Flow atrasa; trunk-based é melhor
  • Manter versões antigas em paralelo (ex.: v1 e v2 simultâneos) — adicionar branches release/1.x, release/2.x
Por enquanto, mantenha o fluxo atual. Quando a fricção aparecer, reavalie.