Gerenciar branches de forma organizada é uma das práticas mais importantes em qualquer equipe de desenvolvimento. Um bom fluxo de versionamento garante rastreabilidade, previsibilidade nas entregas e reduz conflitos durante o ciclo de vida de cada Sprint.
Baseado no modelo Git Flow, o workflow que apresento aqui é uma adaptação moderna e prática, utilizada amplamente no mercado em equipes que trabalham com metodologias ágeis e ferramentas como Redmine, Jira, Trello ou GitHub/GitLab Issues.
- Estrutura principal do repositório
- master ou main:
- develop:
- Criando branches de task (feature)
- Commits e Pull Request (PR)
- Correção de bugs encontrados pelo QA
- Correções de bugs em produção
- Encerramento da Sprint e versionamento
- Benefícios desse workflow
- Clareza e rastreabilidade das entregas por Sprint.
- Redução de conflitos de merge.
- Facilidade na revisão de Pull Requests.
- Histórico limpo e versionamento controlado.
- Organização entre desenvolvimento, QA e deploy.
O repositório segue duas principais linhas de desenvolvimento:
contém o código estável e homologado, pronto para produção.
linha de integração onde as novas funcionalidades e correções de Sprint são validadas antes da liberação.
A partir dessas duas branches centrais, todo o ciclo de desenvolvimento é organizado.
Cada nova task atribuída no sistema de gestão deve originar uma branch seguindo um padrão de nomenclatura padronizado. Isso facilita a rastreabilidade da entrega, especialmente quando o time é grande ou o projeto possui várias sprints paralelas.
O padrão recomendado é:
feature/sprintX/RTCY/TituloDaTask
Essa branch deve sempre ser criada a partir da branch develop atualizada, garantindo que a task comece sobre a base mais recente do projeto:
git checkout develop
git pull origin develop
git checkout -b feature/sprint5/RTC102/ImplementarAutenticacaoOAuth
Isso cria a branch da task a partir da develop atualizada.
Durante o desenvolvimento da task, os commits devem ser claros e objetivos, refletindo o progresso da implementação e dos testes unitários.
Ao concluir a task, realize o commit e o push final:
git add .
git commit -m "Finaliza implementação e testes unitários da autenticação OAuth"
git push origin feature/sprint5/RTC102/ImplementarAutenticacaoOAuth
Em seguida, abra um Pull Request (PR) para a branch develop e utilize o seguinte padrão de comentário:
[SPRINT5][RTC102][ImplementarAutenticacaoOAuth][feature]
Isso ajuda o time de revisão e o QA a identificar rapidamente o contexto da entrega.
Caso o QA identifique algum bug durante os testes da Sprint, o desenvolvedor deve corrigir o problema na mesma branch da feature, mantendo o histórico da entrega.
Ao abrir um novo Pull Request ou atualizar o existente, utilize o seguinte padrão de comentário:
[SPRINT5][RTC102][ImplementarAutenticacaoOAuth][bug] Correção na validação do token
Esse formato indica que a PR refere-se a uma correção derivada da mesma task principal, mantendo o controle e a rastreabilidade no fluxo da Sprint.
Para bugs que ocorrem em produção, a abordagem é diferente.
Essas correções devem ser baseadas diretamente na branch master ou main, garantindo que a correção seja aplicada sobre o código em execução.
A nomenclatura segue o padrão:
feature/bugfix/RTCX
Por exemplo:
feature/bugfix/RTC240
Crie a branch, aplique a correção, teste e envie o Pull Request de volta para a branch principal (master ou main).
Após aprovação e merge, é possível gerar uma tag de hotfix, caso necessário.
Ao final de cada Sprint, com todas as tasks revisadas e integradas à develop, é hora de gerar uma tag de versão.
A tag identifica o encerramento formal da Sprint e serve como ponto de referência no histórico do repositório.
O padrão sugerido é:
git tag -a v1.5 -m "Sprint 5 concluída"
git push origin v1.5
Esse versionamento facilita auditorias, rollback e acompanhamento de evolução entre as versões.
Seguir esse modelo de workflow traz diversas vantagens:
Bugfix Branch: Deve ir apenas para main ou também para develop?
Na maioria dos fluxos Git profissionais, incluindo Git Flow, GitHub Flow e variações híbridas bastante usadas em equipes Java/Spring/Quarkus, existe uma regra importante:
Todo bugfix criado a partir da main deve ser incorporado também à develop, caso ela exista.
Por quê?
Porque a branch develop geralmente contém novas features ainda não liberadas.
Se você corrigir o bug apenas na main, o problema voltará a aparecer quando a develop for integrada no futuro release, causando regressão.
Isso significa:
Criar a branch de bugfix a partir da main atualizada
Porque o bug ocorre na versão em produção.
Porque main representa o código estável.
Abrir Pull Request para main
A hotfix corrige imediatamente a versão produtiva.
Depois da aprovação, fazer merge dessa correção também para develop
Existem duas formas comuns:
PR automático do GitHub (bot cria PR de main -> develop)
Ou o desenvolvedor abre manualmente um PR de sincronização
Isso é opcional?
Não, é considerado convencional e altamente recomendado sempre que o time utiliza uma branch develop.
Ignorar isso pode gerar os seguintes problemas:
Reintrodução do bug ao fazer merge de develop em release futuro.
Divergência de código entre main e develop.
Dificuldade de rastreamento, pois hotfixes não aparecem no histórico da release em desenvolvimento.
Considerações finais
Um bom gerenciamento de branches é mais do que uma convenção, é parte essencial da cultura de engenharia de software madura.
Trabalhar com um workflow bem definido baseado no Git Flow permite que o time mantenha consistência, colabore com eficiência e entregue software de qualidade em ciclos ágeis.
Ao aplicar esse processo com disciplina, cada Sprint se torna mais previsível, e o código entregue ganha estabilidade e confiabilidade, o que é o verdadeiro objetivo de um ciclo de desenvolvimento profissional.
Feito!
