Skip to content

git-workflows.md

Latest commit

 

History

History
99 lines (86 loc) · 4.76 KB

git-workflows.md

File metadata and controls

99 lines (86 loc) · 4.76 KB
Raw

Git Workflows

Branch Policy

  • Use a main / develop git flow.
  • Keep the primary checkout on main or develop, not feature branches.
  • Create feature branches from develop.
  • Open normal pull requests against develop.
  • Merge develop into main for release readiness and release publication.
  • Use git worktrees when parallel tasks need isolated branches.

Naming Convention

  • Phase plan doc: docs/phase-X/phase-X-plan.md (e.g. docs/phase-C/phase-C-plan.md).
  • Prose sprint identifiers (doc id: field, headings, running text) use dot notation matching the phase letter's own case: X.# (e.g. C.2).
  • Sprint doc filenames and worktree names use lowercase kebab syntax: sprint-x-#-<description>.md (e.g. docs/phase-C/sprint-c-3-python-release-train.md) — lowercase phase letter, dash-separated from the sprint number, dash-separated from a short kebab-case description.
  • Python companion sprint prose identifiers append -py to the Rust sprint id: X.#-py (e.g. D.2-py).
  • Python companion sprint doc filenames use the same Rust sprint number plus a -py- marker: sprint-x-#-py-<description>.md (e.g. docs/phase-D/sprint-d-2-py-bindings.md).
  • Sprint numbers are contiguous within a phase, starting at 1, with no gaps. See .claude/skills/plan-hardening/sprint-planning-guidelines.md.
  • -py companions do not consume additional entries in the contiguous Rust sprint-number sequence; they inherit the number of the Rust sprint they wrap.
  • Branch names are always lowercase.
  • Integration branch: integrate/phase-x (e.g. integrate/phase-c).
  • Sprint branch: sprint/x-#-<description> (e.g. sprint/c-2-python-release-train), matching its sprint doc's number and description.
  • Python companion sprint branches follow sprint/x-#-py-<description> (e.g. sprint/d-2-py-bindings), again inheriting the Rust sprint number rather than consuming a new one.
  • If a Rust sprint later splits (for example D.4 into D.4 + D.5), any already-existing D.4-py companion remains attached to D.4's retained scope. The newly-created Rust sprint gets its own new companion (D.5-py) only if it exposes bindable sc-composer surface and once its post-split scope is stable enough to document.
  • This naming convention applies going forward; already-shipped phase/sprint docs and branches (phases A and B) are not retroactively renamed.

Pull Request Rule

Every change should follow:

  1. Create a feature branch from develop, or, for phase sprint work, from that phase's integrate/phase-x branch (see Phase Integration Rule below).
  2. Run local validation.
  3. Push the branch.
  4. Open a PR to develop, or, for phase sprint work, to integrate/phase-x.
  5. Wait for CI and review before merge.

Phase Integration Rule

Every phase always uses its integrate/phase-x branch (see Naming Convention above) — sprint work never merges straight into develop:

  1. Create integrate/phase-x from develop before the phase's first sprint starts, if it does not already exist.
  2. Every sprint branch in the phase branches from integrate/phase-x, and its PR targets integrate/phase-x, not develop.
  3. Sprint PRs merge into integrate/phase-x once that sprint's own review passes and CI is green.
  4. integrate/phase-x should periodically merge develop forward in-phase to avoid large end-of-phase conflicts.
  5. Only after every sprint in the phase has merged into integrate/phase-x does the phase-ending review run.
  6. Only after the phase-ending review passes does integrate/phase-x merge into develop. This is the only PR in the phase that targets develop directly.
  7. A phase plan doc's branch: frontmatter value must match this phase's integrate/phase-x name.

Release Rule

  • Release tags must come from main, not from develop or a feature branch.
  • Publishing must follow the order in release/publish-artifacts.toml.
  • Release automation must validate publish order and version alignment before any tag or publish step runs.
  • Release-track PRs (e.g. a release-blocking fix discovered after develop has already merged to main) go straight to main: cut a release/* branch from main, PR into main, publish from main. Do not route through develop first — that costs a second CI cycle and a bidirectional sync before the release gate (which checks commit ancestry, not content) will pass.
  • After publish, backpropagate the release/* branch's commits to develop as routine post-release housekeeping (a normal main -> develop sync PR). This is not a pre-publish gate.

Worktree Rule

  • Do not switch the main checkout away from main for sprint work.
  • Create dedicated worktrees for long-running or parallel tasks.
  • Remove worktrees only after the user approves cleanup.