Skip to content

docs(branching): codify trunk-based Option A workflow #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
omerakben merged 2 commits into from
May 30, 2026
Merged

docs(branching): codify trunk-based Option A workflow #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0cb208d
docs(branching): codify trunk-based Option A workflow in CLAUDE.md + …
omerakben May 30, 2026
8e38610
docs(contributing): use 3750+ pass floor instead of brittle exact count
omerakben May 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ The `templates/` collection in `~/Projects/agents/templates/` is the influence l
## Working in this repo

1. **Run all commands from the repo root.** `bun install`, `bun test`, `bun run dev <command>`, `bun run build:binary`.
2. **Branches:** `main` only on tagged releases. Feature branches: `feat/`, `fix/`, `refactor/`, `test/`, `docs/`. Conventional commit messages.
2. **Branching is trunk-based (Option A, locked 2026-05-29).** `main` is the protected trunk and the only long-lived branch. Every change lands via a short-lived branch -> PR -> green CI -> **squash-merge** -> head branch auto-deletes (merge-commit and rebase-merge are disabled). Prefixes: `feat/`, `fix/`, `refactor/`, `test/`, `docs/`, `chore/`, with a kebab-case slug after the slash, optionally issue-scoped (`fix/123-worktree-reset`). One branch = one PR = one squashed conventional commit = one concern; branch from latest `main` (`git fetch origin && git switch -c feat/<slug> origin/main`), never from another topic branch; never push `worktree-*` scratch branches. Releases are annotated SemVer tags (`vX.Y.Z-alpha.N`) on a green `main`, cut behind a `chore/release-*` PR. `main` is protected for everyone including admins (required `bun test` checks, linear history, no force-push or deletion, PR-before-merge). Full contract: CONTRIBUTING.md § "Branching and merge workflow".
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The reference to the branching and merge workflow in CONTRIBUTING.md is plain text. Consider making it a clickable Markdown link to improve readability and navigation:

Full contract: [Branching and merge workflow](CONTRIBUTING.md#branching-and-merge-workflow).

Comment on lines 79 to +80
3. **Tests must run offline.** Spine tests use `FakeProvider`. Live-provider tests are opt-in only and gated behind env flags.
4. **No emojis in code or commit messages.** No "Co-Authored-By: Claude" footers unless asked.
5. **Never push to GitHub without explicit user approval.** Local commits are fine.
Expand Down
24 changes: 15 additions & 9 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Requirements:
- **Node 18 or newer** for the npm wrapper smoke (`node --version`).
- macOS arm64, macOS x64, Linux x64, or Linux arm64. Windows local development is not currently supported (the npm wrapper and binaries are Unix-only).

The full offline test suite runs in under 30 seconds on a recent machine and should report `3395 pass / 0 fail / 2 skip` against `main`. The two skipped tests are the opt-in live-provider tests described below.
The full offline test suite runs in under 30 seconds on a recent machine and should report `3750+ pass / 0 fail` against `main` (the pass count grows as suites are added; the 2 skipped tests are the opt-in live-provider tests described below).

## Test discipline

Expand Down Expand Up @@ -78,15 +78,21 @@ Common scopes: `readme`, `providers`, `gates`, `cli`, `demo`, `package`, the mil
- **No squash-commit messages with raw model output.** Edit the message before committing.
- **No secret material** (API keys, tokens, customer data, internal hostnames) anywhere in the diff or message.

### Branch naming
### Branching and merge workflow

- `feat/<scope>-<topic>` for new features
- `fix/<scope>-<topic>` for bug fixes
- `refactor/<scope>-<topic>` for refactors
- `docs/<scope>-<topic>` for docs-only changes
- `test/<scope>-<topic>` for test-only additions
The repo is **trunk-based** (locked 2026-05-29). `main` is the protected trunk; everything else is a short-lived branch.

`main` is tag-only. Pushes to `main` happen at release time.
- Branch from the latest `main`: `git fetch origin && git switch -c feat/<slug> origin/main`. Never branch from another topic branch.
- Prefixes: `feat/`, `fix/`, `refactor/`, `test/`, `docs/`, `chore/`. After the slash, a short kebab-case slug, optionally issue-scoped: `fix/123-worktree-reset-on-restart`.
- One branch = one PR = one concern. If a branch grows a second concern, cut a second branch.
- Open the PR the same session and keep branches short-lived. On merge the branch **auto-deletes** — do not delete it by hand.
- Never push `worktree-*` scratch branches; git worktrees stay local.

**Merging.** PRs **squash-merge** into `main` (merge commits and rebase-merge are disabled), so one PR becomes exactly one conventional commit on `main`. The PR title is the squash commit subject, so it must be Conventional-Commit form.
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Use "Conventional Commits format" instead of "Conventional-Commit form" to be consistent with the "Commit conventions" section heading and standard terminology:

The PR title is the squash commit subject, so it must be in Conventional Commits format.


**`main` is protected.** Required status checks (`bun test on ubuntu-latest`, `bun test on macos-latest`), strict/up-to-date, linear history, no force-push, no deletion, PR-before-merge — enforced for everyone including admins. There are no direct pushes to `main`.

**Releases.** Annotated SemVer tags (`vX.Y.Z-alpha.N`) on a green `main` commit, cut behind a `chore/release-*` PR (version bump + CHANGELOG) so the bump itself passes CI. One tag per release; tags are never moved.

## Pull request expectations

Expand Down Expand Up @@ -121,7 +127,7 @@ When adding a new provider adapter or modifying an existing one:
- A maintainer triages within a few days. Triage adds labels and may ask for clarification.
- Substantive PRs get a Codex review pass (see above). The review verdict is recorded in the PR conversation.
- Block-push findings close in a follow-up commit on the PR branch before merge.
- The merge strategy is squash-merge to `finalize/<release>` branches or rebase to feature branches. `main` only receives release tags.
- The merge strategy is **squash-merge into `main`**; the head branch auto-deletes on merge. Release tags are cut on `main` behind a `chore/release-*` PR (see "Branching and merge workflow").
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The reference to the "Branching and merge workflow" section can be made into a clickable relative link to improve document navigation:

(see [Branching and merge workflow](#branching-and-merge-workflow))


## Code of conduct

Expand Down
Loading