Draft trunk-based development: small PRs, protect main, flaky test triage, and merge…
- User
Draft trunk-based development: small PRs, protect main, flaky test triage, and merge queues.
- Assistant
Hmm, the user is asking about trunk-based development practices, specifically mentioning small PRs, protecting main, flaky test triage, and merge queues. They likely want a clear, actionable draft of policies or guidelines for implementing these practices in their team.
I should structure this as a formal draft document, since the user said "draft" and listed specific elements. The response needs to be practical and ready to adapt, so I'll include clear principles, concrete policies, and roles/responsibilities.
The user didn't specify context, so I'll assume they're in a software engineering leadership or process design role. They might be looking for a template to present to their team. I'll avoid over-explaining basics but ensure each point ties back to trunk-based development's goals: fast integration, high quality, and flow.
Flaky test triage and merge queues are more advanced, so I'll detail those specifically since the user called them out. Also, protecting main is non-negotiable in trunk-based dev, so I'll emphasize that.
I should keep the tone authoritative but flexible—this is a draft, after all. No markdown, but clear sections. Let me outline: Principles first, then Policies per each user-mentioned topic, then Roles, then a closing note about iteration. Avoid jargon but stay precise. Here’s a draft document outlining key practices for implementing trunk-based development in a team or engineering culture. It focuses on small, frequent integrations, high main branch health, and automated workflow support.
Trunk-Based Development Workflow & Guidelines
1. Core Principles
- Single Source of Truth: All development happens on
main(ortrunk). Feature branches are short-lived (hours, not days). - Small, Frequent Commits: Changes are kept small and integrated rapidly—aim for PRs under 400 lines of code changed.
- Always Green:
mainmust remain deployable at all times. Broken builds or failing tests block merges. - Automation First: Rely on CI/CD, codeowners, merge queues, and test suites to enforce standards.
2. Policy: Small Pull Requests (PRs)
- Maximum Size: PRs should be small enough to review in ≤ 60 minutes.
- Single Purpose: One PR = one logical change (bug fix, refactor, small feature).
- WIP (Work in Progress) PRs: Use
[WIP]in title or draft PR feature to get early feedback while work is incomplete. - Rule: No PRs > 1000 lines of change without explicit tech lead approval.
3. Policy: Protect
mainBranchBranch protection rules (GitHub/GitLab/Bitbucket equivalent):
- ✅ Require PR reviews (1+ approval, no self-approval).
- ✅ Require status checks to pass (CI build, tests, lint, security scan).
- ✅ Require linear commit history (squash merge or rebase).
- ✅ Restrict pushes: only via PRs; no direct commits.
- ✅ Require conversation resolution before merging.
- ✅ Optional: Require review from codeowners for critical paths.
4. Process: Flaky Test Triage
Goal: Eliminate flaky tests from blocking merges or causing false positives.
Immediate Response:
- Any PR failing due to a non-deterministic test → skip test (if safe) or mark as flaky.
- Create a triage ticket (Jira/GitHub Issue) with:
- Test name/file
- Steps to reproduce (if known)
- Frequency/pattern
- PR/commit where it was noticed
Triage Cadence:
- Daily: Team identifies top 3 flaky tests.
- Ownership: Assign test owner (or closest domain expert) to fix within 48 hours.
- Mitigation:
- Temporarily quarantine flaky test (move to
@flakytag or separate suite). - If quarantine isn’t possible, disable test and add
@flaky+ ticket link. - Never ignore; track in a dashboard.
- Temporarily quarantine flaky test (move to
Prevention:
- Add test stability checks to CI (e.g., run test multiple times on failure).
- Invest in test reliability: avoid time-based tests, external dependencies, shared state.
5. Policy: Merge Queues
Purpose: Ensure
mainstays green by merging PRs in serial order after validation.How it works (GitHub Merge Queue / GitLab Merge Trains / custom):
- PR gets approved + all required checks pass on the PR’s head.
- PR is added to the merge queue.
- Queue merges PRs one at a time:
- Each PR is rebased onto current
main(fresh). - Full CI runs again on the rebased state.
- If all checks pass, PR merges.
- If fails, PR is removed from queue, assigned to author/team to fix.
- Each PR is rebased onto current
- First in queue merges → next PR in queue starts validation.
Rules:
- Only PRs with initial passing checks may enter the queue.
- Queue should have max 5–10 PRs; if longer, pause and investigate bottlenecks.
- PRs in queue for >1 hour without starting → auto-remove + notify author.
6. Roles & Responsibilities
Role Responsibility Developer Write small PRs, keep tests green, respond to flaky test tickets, rebase if needed. Reviewer Review within 4 business hours; focus on logic, not style (handled by linters). Tech Lead / EM Approve large PRs, oversee flaky test triage, monitor queue health. Platform / CI Engineer Maintain merge queue, CI speed (<15 min), test stability tooling.
7. Metrics to Track
- PR Cycle Time: From open to merge (target: < 4 hours for small PRs).
- Merge Queue Efficiency: % of PRs succeeding on first queue attempt.
- Flaky Test Count: Trend downward weekly.
mainUptime: % timemainis in a deployable state (target: 99.9%+).
8. Exceptions & Escalation
- Large Refactors: If a large change is unavoidable, break into sequential PRs (each independently functional).
- Hotfixes: Bypass queue only for critical production issues (P0). Document reason; follow up with post-mortem.
- Emergency: If queue stuck due to infrastructure, tech lead may manually merge after validation.
9. Culture & Communication
- Daily Standup: Mention flaky test ownership; queue status.
- Retrospectives: Discuss PR size, review latency, merge friction.
- Onboarding: New hires trained on trunk-based flow within first week.
Summary
Trunk-based development with these practices reduces integration hell, improves flow, and maintains high code quality. Success depends on discipline (small PRs), automation (merge queues, flaky test handling), and team ownership (everyone responsible for
mainhealth).
Adapt this draft to your team’s tooling (GitHub, GitLab, Azure DevOps), scale, and compliance needs. Review quarterly.
- Single Source of Truth: All development happens on
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.