Skip to content

Latest commit

 

History

History
229 lines (177 loc) · 7.46 KB

007-trunk-based-development.md

File metadata and controls

229 lines (177 loc) · 7.46 KB

ADR-007: Trunk-Based Development Strategy

Status: Accepted
Date: 2025-11-14
Deciders: Architecture Team
Context: Version Control and Change Management Strategy

Context

We need to define a standardized version control workflow for the microservices architecture project. The workflow must:

  • Support continuous integration and continuous delivery (CI/CD)
  • Minimize merge conflicts and integration issues
  • Align with our Kanban methodology (continuous flow)
  • Enable rapid feedback cycles
  • Work well with microservices and event-driven architecture
  • Support multiple teams working simultaneously
  • Facilitate easy rollbacks and hotfixes
  • Scale as the team and codebase grow

Decision

We will adopt Trunk-Based Development (TBD) with short-lived feature branches as our primary version control strategy.

Key Principles

  1. Single Main Branch: main (or master) is the single source of truth
  2. Short-Lived Branches: Feature branches live for maximum 2-3 days
  3. Frequent Integration: Merge to main at least once per day
  4. Feature Flags: Use feature toggles for incomplete features
  5. Automated Testing: Comprehensive CI/CD pipeline with automated tests
  6. Small Commits: Commit small, incremental changes frequently
  7. Release from Main: All releases are created directly from the main branch

Workflow Model

main (trunk)
  │
  ├─── feature/TASK-001-add-order-validation (1-2 days)
  │      └─── merge to main
  │
  ├─── feature/TASK-002-payment-integration (2-3 days)
  │      └─── merge to main
  │
  ├─── hotfix/FIX-urgent-payment-bug (< 1 day)
  │      └─── merge to main
  │
  └─── release/v1.2.0 (tag only, not a branch)

Branch Types

  1. main: The trunk - always deployable
  2. feature/TASK-XXX-description: Short-lived feature branches (1-3 days max)
  3. hotfix/FIX-description: Emergency fixes (< 1 day)
  4. release/vX.Y.Z: Tags only, not branches (created from main)

Alternative Considered: Git Flow

We also evaluated Git Flow but decided against it for the following reasons:

Git Flow Structure:

  • Long-lived develop and main branches
  • Feature branches from develop
  • Release branches for preparing releases
  • Hotfix branches from main

Why Not Git Flow:

  • ❌ Too much ceremony for continuous deployment
  • ❌ Long-lived branches increase merge conflicts
  • ❌ Slower integration cycles
  • ❌ Complex branch management overhead
  • ❌ Not optimal for microservices (each service can release independently)
  • ❌ Contradicts Kanban continuous flow principles

When Git Flow Makes Sense:

  • Multiple production versions maintained simultaneously
  • Scheduled release cycles (e.g., quarterly)
  • Desktop/mobile apps with app store approval delays
  • Large teams with slower release cadence

For reference, Git Flow remains documented as an alternative strategy in our guides.

Rationale

Why Trunk-Based Development?

  1. Continuous Integration

    • Developers integrate code multiple times per day
    • Early detection of integration issues
    • Reduces "integration hell"

  2. Faster Feedback

    • Code reaches main branch quickly
    • Automated tests run on every commit
    • Issues discovered and fixed rapidly

  3. Reduced Merge Conflicts

    • Short-lived branches minimize divergence
    • Frequent merges keep code synchronized
    • Less time spent resolving conflicts

  4. Better for Microservices

    • Each service can release independently
    • No coordination overhead between services
    • Aligns with microservices autonomy

  5. Supports Kanban

    • Continuous flow without batch releases
    • Work items move smoothly through pipeline
    • No waiting for release windows

  6. Enables CI/CD

    • Main branch always deployable
    • Automated deployment pipelines
    • Rapid delivery to production

  7. Industry Best Practice

    • Used by Google, Facebook, Netflix, Amazon
    • Proven at scale with thousands of developers
    • Supported by DevOps Research and Assessment (DORA) metrics

Supporting Practices

  1. Feature Flags/Toggles

    • Deploy incomplete features hidden behind flags
    • Enable gradual rollout
    • Quick rollback without code changes

  2. Comprehensive Testing

    • Unit tests (>80% coverage)
    • Integration tests for critical paths
    • Contract tests for events
    • Automated E2E tests

  3. Code Review Process

    • All changes reviewed before merge
    • Automated checks (linting, tests, security)
    • Maximum 24-hour review turnaround

  4. Monitoring and Observability

    • Structured logging
    • Metrics and dashboards
    • Alerts for anomalies
    • Quick rollback capability

Consequences

Positive

  • ✅ Faster time to production
  • ✅ Reduced integration problems
  • ✅ Improved code quality through frequent review
  • ✅ Better alignment with Kanban workflow
  • ✅ Simplified branch management
  • ✅ Enables true continuous deployment
  • ✅ Easier rollbacks (linear history)
  • ✅ Better team collaboration

Negative

  • ⚠️ Requires discipline and training
  • ⚠️ Need robust automated testing
  • ⚠️ Feature flags add complexity
  • ⚠️ May feel uncomfortable for teams used to Git Flow
  • ⚠️ Requires good CI/CD infrastructure

Mitigations

  1. Training: Provide comprehensive onboarding and documentation
  2. Tooling: Invest in CI/CD pipeline and feature flag management
  3. Monitoring: Implement robust observability to catch issues early
  4. Culture: Foster trust and encourage frequent small commits
  5. Support: Architecture team available for questions and guidance

Implementation Plan

  1. Phase 1: Foundation (Week 1)

    • Create comprehensive workflow documentation
    • Set up branch protection rules
    • Configure CI/CD pipelines

  2. Phase 2: Training (Week 2)

    • Team training sessions
    • Pair programming to demonstrate workflow
    • Create example pull requests

  3. Phase 3: Pilot (Week 3-4)

    • Start with one microservice
    • Gather feedback
    • Adjust processes as needed

  4. Phase 4: Rollout (Week 5+)

    • Apply to all microservices
    • Monitor metrics (lead time, deployment frequency)
    • Continuous improvement

Metrics for Success

  • Deployment Frequency: Daily deployments to production
  • Lead Time: < 24 hours from commit to production
  • Mean Time to Recovery: < 1 hour
  • Change Failure Rate: < 15%
  • Branch Lifetime: Average < 2 days
  • Code Review Time: < 4 hours

References

Related Documents

Notes

This decision can be revisited if:

  • Team size exceeds 100 developers
  • Deployment frequency requirements change significantly
  • Multiple production versions need to be maintained
  • Regulatory requirements demand different release processes