Playbook : Trunk-Based Development (TBD) Playbook

🌐 Purpose

To establish consistent engineering practices for Trunk-Based Development (TBD) that promote fast feedback, reduce integration risk, and support continuous delivery.

⚖️ Principles

  • Develop on a single shared branch ("trunk" or "main")
  • Keep all changes small, atomic, and frequently integrated
  • Avoid long-lived feature branches or forks
  • Embrace continuous integration and automated testing
  • Build quality in early and often

✅ Benefits

  • Reduces merge conflicts and integration hell
  • Enables faster release cycles and feature delivery
  • Improves team collaboration and visibility
  • Encourages high-quality, testable, and maintainable code

⚡ Key Practices

1. Single Source of Truth

  • All developers commit to main (or trunk) branch
  • Use short-lived feature toggles, not long-lived branches

2. Small, Frequent Commits

  • Break down work into small, testable pieces
  • Commit multiple times per day

3. Feature Toggles

  • Use feature flags to hide incomplete features in production
  • Avoid conditional logic bloat

4. Pre-Commit Checks

  • Local testing and linting before pushing
  • Validate that all code meets minimum quality thresholds

5. Continuous Integration (CI)

  • CI pipeline triggers on every commit
  • Includes unit, integration, security, and performance tests

6. Fast Feedback

  • Aim for pipeline execution time under 10 minutes
  • Triage and fix broken builds as a priority

7. Shared Ownership

  • Everyone owns the state of main
  • Rotate code review responsibilities to distribute knowledge

8. Pair/Mob Programming

  • Encourage collaborative coding to support learning and rapid delivery

9. Testing in Production

  • Use observability tools and metrics to monitor releases
  • Validate feature impact in real time using flags and logs

🔧 Tooling Recommendations

  • Version Control: Git, GitHub/GitLab/Bitbucket
  • CI/CD: GitHub Actions, CircleCI, GitLab CI, Jenkins
  • Feature Flags: LaunchDarkly, Unleash, Flipper
  • Quality Gates: SonarQube, ESLint, Prettier
  • Observability: Grafana, Prometheus, Honeycomb

🌍 Applicability & Exceptions

  • Recommended for all digital product teams delivering frequently
  • If regulation or approval processes restrict direct-to-main commits, use short-lived branches with auto-merge to main

🔄 Continuous Improvement

  • Retrospect quarterly on trunk-based practice adoption
  • Measure commit frequency, PR lifetime, and pipeline stability
  • Identify blockers to fast integration and reduce them

🔹 Metrics to Monitor

  • Average commits per developer per day
  • % of builds passing on first try
  • Average PR lifetime (goal: <1 day)
  • Frequency of trunk merges per day
  • Incidents tied to trunk changes (via post-mortem tagging)

📖 References

  • Accelerate by Forsgren, Humble, Kim
  • Trunk-Based Development (trunkbaseddevelopment.com)
  • GitLab Flow & GitHub Flow

This playbook aligns with:

  • Policy: Engineering Excellence First
  • Standards: Enforce CI for Every Code Change, Reduce WIP, Promote Continuous Learning