Skip to main content

GitHub Workflow

Este guia mostra como usar nosso modelo de branching e estratégia de lançamento, combinando o Git Flow com a GitHub CLI.

Modelo de Branching​

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

BranchFinalidadeEstabilidade
mainLançamentos em produção. Cada commit é um lançamento com tag.Ultraestável
developDesenvolvimento do próximo lançamento. Branch de integração.Estável
feature/*Novas funcionalidades ou alterações de interface. Crie a branch a partir de develop.Experimental
bugfix/*Correções de bugs para o próximo ciclo de desenvolvimento.Experimental
release/*Preparação para um novo lançamento em produção.Polimento final
hotfix/*Correções de bugs críticos para a versão de produção.Urgente
support/*Branches de suporte de longo prazo para versões principais mais antigas.Estável

Configuração do Git Flow CLI​

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 Ferramentas​

Para seguir este workflow 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): Usado para Pull Requests, monitoramento de status e lançamentos oficiais.

1. Iniciando uma Nova Funcionalidade​

Sempre crie uma branch a partir de develop. Consulte a Referência de Comandos para obter o comando exato do git flow.

2. Colaborando e Propondo Alterações​

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

  1. Envie sua branch para o repositório remoto usando push.
  2. Crie um Pull Request direcionado a develop (consulte a Referência de Comandos para o comando gh pr).

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

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

  • Ação: Faça o merge via interface do GitHub ou CLI usando o método squash (consulte a Referência de Comandos para obter o comando exato da CLI).

Workflow de Lançamento e Versionamento (Changesets)​

Usamos Changesets combinados com GitHub Actions para automatizar nosso versionamento, compilação de changelog e Pull Requests de lançamento. 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 (consulte a Referência de Comandos).
  2. Selecione os pacotes que foram modificados usando a barra de espaço.
  3. Escolha o nível de incremento SemVer apropriado (Major para alterações que quebram a compatibilidade, Minor para novas funcionalidades retrocompatíveis ou Patch para correções de bugs).
  4. Forneça uma descrição técnica 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. Faça o commit deste arquivo markdown junto com seu código e envie-o com sua feature branch.
Mantenha os Changesets Pequenos

Crie um changeset por alteração isolada. Se uma feature branch tiver várias correções ou adições independentes, execute pnpm version:changeset várias vezes para gerar notas separadas para cada uma.

2. Pipeline de Versionamento Automatizado (GitHub Actions)​

Nosso workflow de CI/CD gerencia o incremento de versão automaticamente quando o código é integrado:

  1. Pull Request e Integração: Os desenvolvedores abrem um Pull Request direcionado à branch develop.
  2. Merge em develop: Uma vez aprovado e integrado em develop, a GitHub Action Manage Version Bumps and Releases é acionada.
  3. Geração de PR de Lançamento:
    • O workflow analisa os arquivos .changeset/*.md presentes na branch.
    • Ele calcula as novas versões, consome (exclui) os arquivos markdown temporários de changeset, atualiza os respectivos arquivos package.json e atualiza os changelogs locais dos pacotes.
    • Ele faz o commit dessas alterações automaticamente e cria (ou atualiza) um Pull Request aberto no GitHub chamado chore(release): version packages direcionado a develop.

3) Finalizando o Lançamento (Apenas Mantenedores)​

Para publicar e finalizar o lançamento:

  1. Abra o Pull Request automatizado chore(release): version packages no GitHub.
  2. revise as alterações de versão compiladas e os changelogs.
  3. Faça o merge do Pull Request em develop. Como os arquivos de changeset já foram consumidos e excluídos, fazer o merge deste PR consolida as versões de pacotes atualizadas no repositório.
Sem Alterações Manuais de Versão

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

Correções Críticas (Hotfixes)​

Se um bug for encontrado em produção:

  1. Inicie e finalize uma hotfix branch.
  2. Consulte a Referência de Comandos para obter os comandos exatos do git flow hotfix.
  3. Sincronize main e develop.
  • Sem commits diretos em main ou develop: Sempre use feature branches e PRs.
  • Sem Push Forçado: A menos que seja em sua própria feature branch isolada e necessário para um rebase.
  • Sem Merges Sujos: Evite fazer o merge de main de volta em feature/*. Sempre faça o rebase em develop se sua feature branch ficar desatualizada.