Pular para o conteúdo principal

Guia de Fluxo de Trabalho Git

Este documento descreve a estratégia profissional de ramificação e lançamento para o Elo Orgânico, combinando a disciplina estrutural do Git Flow com o poder de colaboração da GitHub CLI (gh).

Modelo de Ramificação (Branching)​

Seguimos o modelo padrão Git Flow para garantir a estabilidade do nosso código de produção, adaptado para nossa estrutura de monorepo.

BranchPropósitoEstabilidade
mainLançamentos de produção. Cada commit é uma release tagueada.Ultra Estável
developDesenvolvimento da próxima release. Branch de integração.Estável
feature/*Novas funcionalidades ou mudanças de UI. Ramifica de develop.Experimental
bugfix/*Correções de bugs para o próximo ciclo de desenvolvimento.Experimental
release/*Preparação para uma nova release de produção.Polimento Final
hotfix/*Correções de bugs críticos para a versão de produção.Urgente
support/*Ramificações de suporte de longo prazo para versões major antigas.Estável

Configuração da CLI do Git Flow​

Nosso repositório local está configurado com os seguintes prefixos e regras de tag:

Branch name for production releases: main
Branch name for "next release" development: develop
Feature branch prefix: feature/
Bugfix branch prefix: bugfix/
Release branch prefix: release/
Hotfix branch prefix: hotfix/
Support branch prefix: support/
Version tag prefix: v

Requisitos de Ferramental​

Para seguir este fluxo de trabalho de forma eficiente, recomendamos:

  1. Git Flow CLI (Edição AVH): Geralmente incluído no Git for Windows ou disponível via pacote gitflow.
  2. GitHub CLI (gh): Utilizada para Pull Requests, monitoramento de status e releases oficiais.

Padrões de Commit (Conventional Commits)​

Para manter um histórico limpo e automatizado, todos os commits devem seguir a especificação Conventional Commits.

Formato: <tipo>(<escopo>): <descrição>

Tipos​

  • feat: Uma nova funcionalidade (correlaciona-se com MINOR no SemVer).
  • fix: Uma correção de bug (correlaciona-se com PATCH no SemVer).
  • docs: Mudanças apenas na documentação.
  • style: Mudanças que não afetam o significado do código (espaço em branco, formatação, etc).
  • refactor: Uma alteração de código que não corrige um bug nem adiciona uma funcionalidade.
  • perf: Uma alteração de código que melhora a performance.
  • test: Adição de testes ausentes ou correção de testes existentes.
  • chore: Mudanças no processo de build ou ferramentas/bibliotecas auxiliares.

Escopos do Monorepo​

Use o contexto ou nome do pacote como escopo:

  • instance: Mudanças nos apps ou core da Instância da Comunidade.
  • portal: Mudanças nos apps ou core do Portal Global.
  • core: Mudanças na lógica de domínio compartilhada.
  • studio: Tokens de design, ativos ou configuração do Penpot.
  • tools: Servidores MCP, scripts ou infraestrutura.
  • deps: Atualizações de dependências (gerenciadas via catalogs).

Exemplo: feat(instance): add Pix payment reconciliation to checkout

Fluxo de Contribuição​

1. Iniciando uma Nova Funcionalidade​

Sempre ramifique a partir de develop.

git flow feature start minha-funcionalidade-incrivel

2. Colaborando e Propondo Mudanças​

Em vez de realizar o merge localmente, usamos Pull Requests para revisão de código e validação de CI.

  1. Envie sua branch: git push -u origin feature/minha-funcionalidade-incrivel
  2. Crie um Pull Request: 
    gh pr create --base develop --fill --web
    Use --fill para usar automaticamente suas mensagens de commit para a descrição do PR.

3. Estratégia de Merge Sênior (Squash & Merge)​

Para manter o histórico da develop limpo e significativo, usamos Squash Merges. Isso combina todos os commits de uma branch de funcionalidade em um único commit bem descrito na develop.

  • Ação: Merge via interface do GitHub ou CLI usando o método squash.
  • Comando CLI: gh pr merge --squash --delete-branch

Fluxo de Release & Versionamento (Changesets)​

Utilizamos o Changesets combinado com o GitHub Actions para automatizar o nosso versionamento, compilação de changelogs e criação de Pull Requests de release. Os desenvolvedores não alteram manualmente as versões dos pacotes nos arquivos package.json.

1. Gerando um Changeset (Local)​

Quando sua funcionalidade ou correção de bug estiver pronta e antes de abrir um Pull Request:

  1. Execute a ferramenta interativa de changeset a partir da raiz do repositório: 
    pnpm version:changeset
  2. Selecione o(s) pacote(s) que foram modificados utilizando a barra de espaço.
  3. Escolha o nível de SemVer apropriado (Major para alterações que quebram compatibilidade, Minor para novas funcionalidades retrocompatíveis ou Patch para correções de bugs).
  4. Forneça uma descrição técnica e clara da alteração (em inglês, em conformidade com nossos padrões de commit).
  5. Um arquivo markdown temporário será criado no diretório .changeset/ (por exemplo, .changeset/warm-dogs-run.md).
  6. Comite esse arquivo markdown junto com seu código e envie-o com sua branch de funcionalidade.
Mantenha os Changesets Pequenos

Crie um changeset por alteração isolada. Se uma branch de funcionalidade contiver várias correções ou adições independentes, você pode executar pnpm version:changeset múltiplas vezes para gerar notas separadas para cada uma.

2. Pipeline de Versionamento Automatizado (GitHub Actions)​

Nosso workflow de CI/CD gerencia o bump de versão de forma automatizada quando o código é integrado:

  1. Pull Request & Integração: Os desenvolvedores abrem um Pull Request direcionado à branch develop.
  2. Merge para develop: Uma vez aprovado e mesclado na develop, o workflow de GitHub Actions Manage Version Bumps and Releases é acionado automaticamente.
  3. Geração do PR de Release:
    • O pipeline analisa os arquivos .changeset/*.md presentes na branch.
    • Ele calcula as novas versões, consome (deleta) os arquivos markdown temporários de changeset, faz o bump dos respectivos arquivos package.json e atualiza os arquivos de changelog de cada pacote.
    • Ele comita essas mudanças automaticamente e abre (ou atualiza) um Pull Request no GitHub intitulado chore(release): version packages com destino à branch develop.

3. Finalizando a Release (Apenas Mantenedores)​

Para publicar e consolidar a release:

  1. Abra o Pull Request automatizado chore(release): version packages no GitHub.
  2. Revise as alterações de versão e changelogs gerados.
  3. Faça o merge do Pull Request na branch develop. Como os arquivos de changeset já foram consumidos e removidos, mesclar este PR consolida as novas versões de pacotes no repositório.
Sem Bumps de Versão Manuais

Nunca edite o campo "version" no package.json de um pacote manualmente durante o desenvolvimento de uma branch. Sempre use pnpm version:changeset e permita que o pipeline do GitHub Actions gerencie os lançamentos.

Correções Críticas (Hotfixes)​

Se um bug for encontrado em produção:

  1. git flow hotfix start fix-crash
  2. Aplique a correção e finalize: git flow hotfix finish fix-crash
  3. Sincronize tanto a main quanto a develop.

Práticas Proibidas​

  • Sem commits diretos na main ou develop: Sempre use branches de funcionalidade e PRs.
  • Sem Force Pushes: A menos que seja em sua própria branch de funcionalidade isolada e necessário para um rebase.
  • Sem Dirty Merges: Evite fazer merge da main de volta para feature/*. Sempre faça rebase sobre a develop se sua branch de funcionalidade ficar desatualizada.

A adesão a este fluxo de trabalho garante um histórico limpo e uma distribuição de software de alta qualidade.