Fluxo de trabalho

Fluxo de trabalho (Git Flow)

Referência canônica, compartilhada com o backend: Boas Práticas — Segue o fluxo.

Branches de ambiente

Branch	Ambiente	URL
main	Produção	basedosdados.org
staging	Pré-produção / QA	staging.basedosdados.org
development	Integração / testes	development.basedosdados.org

Nunca faça commit ou push direto nessas branches. Toda mudança entra por pull request.

Um push em qualquer uma delas dispara o build da imagem Docker e o deploy no ambiente correspondente.

Uma branch, três PRs

main ──┬──────────────────────────────────────────► (PR 3) main
       │
       └─► feat/minha-feature ──┬─► (PR 1) development
                                ├─► (PR 2) staging
                                └─► (PR 3) main

1. Crie a branch a partir de main, nunca de staging ou development.

   git checkout main && git pull
   git checkout -b feat/minha-feature

   Nomeie a branch pela intenção: feat/…, fix/…, chore/…, docs/…, refactor/…. Uma mudança lógica por branch.
2. Abra três PRs com a mesma branch: um para development, um para staging e um para main. Não crie uma branch para cada destino nem faça cherry-pick.
3. Faça merge com merge commit ou fast-forward. Nunca use squash. O squash cria um commit novo em cada branch e quebra o histórico compartilhado de que os resets dependem.
4. Ordem usual: development → validar → staging → QA → main.

Exceção — documentação: mudanças só de docs (README, CONTRIBUTING, comentários) normalmente vão apenas para main. Abra os PRs para development e staging só se a equipe achar relevante.

Como a mesma branch é mesclada nos três destinos, os commits da feature têm o mesmo SHA em todos os ambientes. Só os merge commits mudam.

Resets quinzenais

Os ambientes se distanciam conforme os merge commits se acumulam. Por isso, a equipe reseta staging e development para main mais ou menos a cada duas semanas.

Consequências:

• Uma mudança só sobrevive se chegar em main. O que existir apenas em staging ou development é descartado no próximo reset.
• Logo depois de um reset, um PR de branch criada a partir de main entra limpo em development e staging. Quanto mais tempo passa, mais commits de main o PR arrasta. Se o destino estiver muito diferente, espere o reset em vez de forçar um merge com muito ruído.

O que não fazer

• Mesclar uma branch de ambiente em outra (ex.: staging → main) para promover uma feature.
• Criar a branch da feature a partir de development ou staging.
• Usar squash merge.
• Fazer push direto em main, staging ou development.

Automações nos PRs

• Mergify: atualiza automaticamente PRs desatualizados em relação ao destino (exceto drafts e PRs com conflito). Quando há conflito, comenta no PR e adiciona o label conflict.
• Cypress: PRs para main que alteram next/ rodam os testes end-to-end (.github/workflows/cypress-tests.yml). Veja Testes com o Cypress.

Checklist antes de abrir os PRs

• git branch --show-current mostra a sua branch de feature
• A branch foi criada a partir de um main atualizado
• O site roda localmente sem erros (npm run dev)
• Textos novos têm tradução em pt, en e es (public/locales/)
• Três PRs abertos: development, staging e main (para mudanças só de docs, normalmente só main)