docs: define branch and worktree lifecycle - #342
Conversation
📝 WalkthroughWalkthroughAGENTS.md adds a “Branch and Worktree Lifecycle” section defining procedures for branch deletion verification, stale reference pruning, closed-but-unmerged pull request classification, state capture, dirty worktree handling, and post-cleanup reporting. ChangesBranch and Worktree Lifecycle
Estimated code review effort: 1 (Trivial) | ~2 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@AGENTS.md`:
- Around line 138-141: Update the branch/worktree deletion guidance to require
dirty-worktree commits be pushed to a named branch or PR, or otherwise
explicitly preserved outside the branch being deleted, before deletion. Retain
the existing requirements to review the changes and explicitly keep or discard
them.
- Around line 131-134: Update the branch cleanup guidance around
delete_branch_on_merge to recheck that the remote head branch still points to
the merged PR head before any manual deletion. Require explicit authorization
immediately before deleting it, and retain the existing git fetch --prune step
without altering local branches or worktrees.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| - Keep GitHub's `delete_branch_on_merge` enabled. After verifying a merge, | ||
| confirm that the remote head branch is gone; delete it manually only if | ||
| auto-delete did not run. Then use `git fetch --prune` to remove stale local | ||
| tracking refs without touching local branches or worktrees. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Verify the remote branch tip before manual deletion.
A merged PR’s head branch may have advanced or been reused after the merge. Require rechecking that the remote branch still points to the merged PR head, and obtain explicit authorization before deleting it; otherwise the fallback can remove unrelated post-merge work.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@AGENTS.md` around lines 131 - 134, Update the branch cleanup guidance around
delete_branch_on_merge to recheck that the remote head branch still points to
the merged PR head before any manual deletion. Require explicit authorization
immediately before deleting it, and retain the existing git fetch --prune step
without altering local branches or worktrees.
Source: Learnings
| - Before deleting a local branch or worktree, record its PR state, HEAD, | ||
| upstream/push state, and whether its worktree is clean. A dirty worktree | ||
| must be reviewed and either committed as its own contract, explicitly kept, | ||
| or explicitly discarded; never delete it merely to reduce branch count. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Preserve dirty-worktree commits beyond local branch deletion.
“Committed as its own contract” is insufficient if the commit remains only on the branch being deleted. Require the changes to be pushed to a named branch/PR or otherwise explicitly preserved before deleting the branch or worktree.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@AGENTS.md` around lines 138 - 141, Update the branch/worktree deletion
guidance to require dirty-worktree commits be pushed to a named branch or PR, or
otherwise explicitly preserved outside the branch being deleted, before
deletion. Retain the existing requirements to review the changes and explicitly
keep or discard them.
Source: Learnings
Change contract
Document verified branch and worktree lifecycle rules: auto-delete merged PR heads, classify closed-unmerged work, and review dirty worktrees before cleanup.
Out of scope
Business code, collector/runtime behavior, deployment, and automatic deletion of closed-unmerged branches.
Dependency or merge order
None; targets current
main.Focused validation
git diff --checkdelete_branch_on_merge=true.Rollout/rollback impact
Documentation and repository setting only. Revert this one commit to remove the written policy; the GitHub setting can be toggled independently.
Summary by CodeRabbit