Worktree branch policy: never on development or main - #148
Merged
Merged
Conversation
Document the rule that's been operating implicitly in this repo:
* `main` is the release branch (tagged quarterly, read-only history).
* `development` is the integration trunk where active work converges.
* The default repo checkout (~/+Underworld/underworld3-pixi) sits on
`development` — that's where you read current state and pull.
* All work — even work that will merge to `development` — happens
on a side branch (feature/, bugfix/, docs/) in a worktree.
`./uw worktree create` already enforces this for new worktrees (it
creates `<prefix>/<name>` and resets to origin/development). Two
small tightenings here:
1. `./uw worktree create x development` (or `main`) is now refused
with a clear message pointing the user at either the main repo
or a regular side-branch prefix.
2. `./uw worktree list` flags any worktree currently on `development`
or `main` with a yellow ⚠ advisory and a "branch off" suggestion.
Useful for surfacing pre-existing violations (e.g. worktrees
created with `git worktree add` directly).
Documentation added in two places:
- CLAUDE.md "Worktree branch policy" subsection under Git Worktrees
- docs/developer/guides/branching-strategy.md detailed rationale
The default checkout-on-development rule is restated in both.
Underworld development team with AI support from Claude Code (https://claude.com/claude-code)
Contributor
There was a problem hiding this comment.
Pull request overview
Documents and enforces the repository’s existing Git worktree branching policy: the main checkout stays on development for integrating/pulling, while all worktree-based work happens on side branches and never directly on development or main.
Changes:
- Refuse
./uw worktree create <name> development|mainwith a clear guidance message to use side-branch prefixes. - Add a warning advisory in
./uw worktree listwhen a worktree is currently ondevelopmentormain. - Document the policy and rationale in contributor docs (CLAUDE.md + branching strategy guide).
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
uw |
Enforces the policy at worktree creation time and surfaces existing violations in worktree listing output. |
docs/developer/guides/branching-strategy.md |
Adds a “worktrees are always on a side branch” policy section with rationale and do/don’t guidance. |
CLAUDE.md |
Adds a concise worktree branch policy subsection for AI/human workflow alignment. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Member
Author
|
Trivial change to policy docs ... waving this through. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the worktree branch policy that's been operating implicitly:
mainis the release branch (tagged quarterly, read-only history)developmentis the integration trunk where active work convergesdevelopment— for reading current state and pullingfeature/,bugfix/,docs/), then merges todevelopmentvia PRWhat's tightened
./uw worktree create x development(ormain) is now refused with a clear message pointing the user at either the main repo or a side-branch prefix../uw worktree listflags any worktree currently ondevelopmentormainwith a yellow ⚠ advisory and a "branch off" suggestion. Surfaces pre-existing violations.Documentation added in CLAUDE.md (Worktree branch policy subsection under Git Worktrees) and docs/developer/guides/branching-strategy.md (detailed rationale section).
Test plan
bash -n uwpasses./uw worktree create test-rejection developmentis refused with the expected message./uw worktree listshows the ⚠ advisory next to any pre-existing worktree ondevelopmentNote: existing violation
This branch surfaces (but does NOT auto-fix) one existing violation:
region-ds-cell-labelsworktree is currently on[development]. Theadvisory in
./uw worktree listflags it; the owner of that workshould branch off to e.g.
feature/region-ds-cell-labelsbeforetheir next commit.
🤖 Generated with Claude Code