Trunk-Based Development — o que é, princípios e trabalho em um único branch

O que é Trunk-Based Development?

Trunk-Based Development (TBD) é uma metodologia de gerenciamento de versões onde todos os desenvolvedores integram suas alterações em um único branch principal (trunk, main ou master) várias vezes ao dia. Ao contrário do Git Flow com seus branches de funcionalidade de longa duração, o TBD minimiza o tempo de vida dos branches para algumas horas, raramente para 1–2 dias. O objetivo principal é evitar o “inferno do merge” (merge hell), quando uma grande funcionalidade é mesclada ao trunk após semanas de desenvolvimento.

De acordo com Google Cloud DevOps, 2024, Trunk-Based Development é uma das práticas-chave de equipes DevOps de alto desempenho. O State of DevOps Report (Puppet, 2023) mostrou que equipes que usam TBD se recuperam 30% mais rápido de falhas e enfrentam 50% menos defeitos críticos em produção. TBD é obrigatório para Continuous Deployment.

Trunk-Based Development não significa que os desenvolvedores fazem commits diretamente no trunk sem revisão. No TBD, são usados branches de funcionalidade de curta duração que, após criar um MR e uma revisão de código rápida (em algumas horas), são mesclados ao trunk. Se a revisão levar mais de um dia, a funcionalidade precisa ser dividida em partes menores.

State of DevOps Report: dados sobre TBD

O State of DevOps Report anual (Puppet/DORA) rastreia as práticas de equipes de alto desempenho. Desde 2015, o TBD está entre as 3 principais práticas correlacionadas com alta frequência de implantação (deploy frequency) e baixo tempo de recuperação (MTTR). Equipes que praticam TBD implantam código 2–3 vezes mais frequentemente e se recuperam 30% mais rápido (DORA, 2023).

Feature Toggles: gerenciando código incompleto sem branches

Feature Toggles (flags de funcionalidade, feature flags) são um mecanismo para ativar e desativar funcionalidades sem alterar código. No TBD, os feature toggles substituem os branches de funcionalidade: o desenvolvedor envia código incompleto ao trunk, mas o oculta atrás de uma flag condicional. Quando a funcionalidade está pronta para exibição, a flag é alternada na configuração sem reimplantação.

De acordo com Martin Fowler, 2024, os feature toggles são divididos em quatro tipos: release toggles (gerenciamento de visibilidade de funcionalidade), experiment toggles (testes A/B), ops toggles (gerenciamento de parâmetros operacionais) e permission toggles (acesso baseado em papéis). Em projetos mobile, os release toggles são especialmente úteis: a nova funcionalidade fica oculta até a data de lançamento, mas o código já está no trunk e passa por CI/CD.

// Feature Toggle no Android com Kotlin
object FeatureManager {
    private val remoteConfig = FirebaseRemoteConfig.getInstance()

    fun isEnabled(key: String): Boolean {
        return remoteConfig.getBoolean(key)
    }
}

// Uso no código
if (FeatureManager.isEnabled("new_checkout_flow")) {
    showNewCheckoutScreen()
} else {
    showOldCheckoutScreen()
}

CI/CD no Trunk-Based Development: práticas obrigatórias

Continuous Integration (CI) é o componente mais importante do TBD. Cada push ao trunk (ou a um branch temporário antes do MR) aciona um pipeline completo: build, testes unitários, testes de integração, linters, análise estática, verificação de cobertura de código. Se pelo menos um estágio falhar, o autor corrige o código antes do próximo commit. “Trunk quebrado — desenvolvimento parado” é a regra principal do TBD.

De acordo com Jez Humble, Continuous Delivery, 2024, Trunk-Based Development requer um pipeline de CI que seja executado em 10–15 minutos. Se o build demorar mais, os desenvolvedores fazem commits com menos frequência, o que destrói o sentido do TBD. Em projetos mobile, os builds de Android e iOS podem levar 20–30 minutos, tornando o TBD menos conveniente. Nesses casos, as equipes usam Short-Lived Feature Branches (branches de 1 dia) com CI imediato.

# GitHub Actions para TBD (Android)
name: CI - TBD Check
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: ./gradlew testDebugUnitTest
      - name: Static analysis
        run: ./gradlew ktlintCheck detekt

Branches de curta duração: regras de trabalho no TBD

Os branches de curta duração (short-lived branches) são um compromisso entre o TBD puro (commits diretos ao trunk) e o Git Flow. Um branch vive no máximo 1–2 dias, contém alterações de 1–3 commits e, após a revisão (no máximo 4 horas de espera), é mesclado ao trunk. Se uma funcionalidade exigir mais tempo, ela é dividida em subtarefas, cada uma com seu próprio branch de curta duração.

De acordo com TBD Documentation, 2024, as regras dos branches de curta duração: o branch é criado a partir de um trunk fresco (não mais de 1 hora), não é sincronizado com o trunk via merge/rebase (se mais de 4 horas passaram, um novo branch é criado), o MR/PR é criado imediatamente após o primeiro commit (mesmo que o trabalho não esteja completo — como Draft).

Pre-tested Commits: commits com garantia

Para Trunk-Based Development, a técnica de pre-tested commits é importante: o desenvolvedor executa o pipeline de CI em seu branch antes de commitar, e somente após um status verde o commit chega ao trunk. No GitLab, isso é implementado por meio de Merge Request pipelines com a opção “Merge when pipeline succeeds”. No GitHub — por meio de branch protection rules com Required status checks. Isso garante que o trunk nunca contenha código quebrado.

• 1–2 dias — tempo máximo de vida de um short-lived branch
• 1–3 commits — tamanho ideal de alterações
• 4 horas — tempo máximo de espera para revisão de código
• Crie o MR imediatamente após o primeiro commit, mesmo em status Draft

Branch by Abstraction: substituindo código sem ramificação

Branch by Abstraction é uma técnica que permite substituir ou alterar significativamente uma parte do sistema sem criar um branch de funcionalidade de longa duração. Em vez de ramificar no Git, o desenvolvedor cria uma abstração (interface) sob a qual funcionam tanto a implementação antiga quanto a nova. Gradualmente, todos os consumidores são migrados para a nova implementação, após o que a antiga é removida.

De acordo com Branch by Abstraction, 2024, as etapas do Branch by Abstraction: 1) criar uma abstração para o componente a ser substituído, 2) implementar a nova versão sob a abstração, 3) alternar os consumidores para a nova implementação via configuração, 4) remover a implementação antiga. Todas as etapas são commitadas no trunk em pequenas porções, cada uma das quais não quebra o CI/CD.

TBD vs Git Flow: comparação de abordagens

Trunk-Based Development e Git Flow são duas abordagens opostas para gerenciamento de branches. Git Flow usa branches de longa duração e uma hierarquia estrita, TBD usa um único branch e ciclos de integração curtos. A escolha entre eles depende do tamanho da equipe, frequência de lançamentos e nível de automação de CI/CD.

Erros típicos ao implementar Trunk-Based Development

Os erros do TBD geralmente estão relacionados a CI/CD insuficiente ou disciplina fraca de commits. O primeiro erro é implementar TBD sem CI, que quebra no primeiro commit falho. Se o trunk não puder ser corrigido em 15 minutos, a equipe perde a confiança no processo e volta para branches longos. O segundo erro é permitir branches de longa duração “só para esta funcionalidade”, o que destrói todo o conceito.

De acordo com Paul Hammant, 2023, o terceiro erro é a má modularidade do código. Trunk-Based Development exige que o código seja dividido em módulos independentes. Se uma alteração em uma classe quebra outros três módulos, os desenvolvedores não conseguem commitar em pequenas porções. O quarto erro é ignorar os feature toggles: tentar enviar código incompleto sem uma flag quebra o trunk para toda a equipe.

Trunk-Based Development no desenvolvimento mobile

Trunk-Based Development em projetos mobile tem particularidades devido aos longos tempos de build (20–30 minutos para Android e iOS) e requisitos rigorosos de qualidade. Google e Spotify usam TBD no desenvolvimento mobile, aplicando branches de curta duração com CI obrigatório antes do merge. Os feature toggles são gerenciados através do Firebase Remote Config ou LaunchDarkly.

De acordo com LaunchDarkly Docs, 2024, no desenvolvimento mobile, o TBD oferece uma vantagem: as funcionalidades são testadas no trunk junto com o restante do código antes da data de lançamento, reduzindo o risco de problemas de integração. Se o pipeline de CI levar mais de 15 minutos, branches de curta duração de 1 dia com CI automático em cada push são ideais. Para Apple App Store e Google Play, o TBD exige a configuração de implantações graduais por meio de feature toggles.

Feature Flags como serviço: LaunchDarkly e Firebase

Para gerenciar feature toggles no TBD, são usadas plataformas: LaunchDarkly (enterprise, completo), Firebase Remote Config (gratuito para projetos pequenos), Split.io (código aberto). Elas fornecem: ativação direcionada de funcionalidades por porcentagem de usuários, testes A/B, monitoramento de uso e desativação automática em caso de erros. Em projetos mobile, o Firebase Remote Config é a escolha mais popular devido à sua integração com Firebase e limite gratuito de até 1000 usuários.