Skip to content

docs: point branching/release sections at engineering handbook #73

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
amcheste merged 1 commit into from
Apr 25, 2026
+9 −46
Merged

docs: point branching/release sections at engineering handbook #73

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
55 changes: 9 additions & 46 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,17 +40,18 @@ git checkout develop

---

## Branch Model
## Branching, Commits, and Releases

| Branch | Purpose |
|--------|---------|
| `main` | Always equals the latest published release — stable, never directly committed to |
| `develop` | Integration branch — all PRs target here |
| `feature/*`, `fix/*`, etc. | Short-lived branches off `develop` |
The branching strategy, commit convention, and release process follow the canonical rules documented in Alan's engineering handbook:

PRs go to `develop`. When enough changes accumulate for a release, `develop` is promoted to `main` via the `/publish-release` skill, which opens the develop→main PR automatically.
- **Why:** [Branching Strategy philosophy](https://github.com/amcheste/engineering-handbook/blob/main/docs/philosophies/branching-strategy.md)
- **How:** [Branching & Releases workflow](https://github.com/amcheste/engineering-handbook/blob/main/docs/workflows/branching-and-releases.md)

## Development Workflow
In short: branch from `develop`, one logical change per PR, [Conventional Commits](https://www.conventionalcommits.org/) (`feat:` / `fix:` / `docs:` / `chore:`, `!` for breaking), and releases are cut by `/publish-release` with a CLI merge from `develop` to `main` (never GitHub's merge button).

---

## Development Workflow (repo-local)

Run `shellcheck` on any modified scripts before committing:
```bash
Expand All @@ -76,21 +77,6 @@ that is not a GUI cask must also appear in `Brewfile.ci`.

---

## Commit Convention

This project uses [Conventional Commits](https://www.conventionalcommits.org/):

| Prefix | Use |
|--------|-----|
| `feat:` | New tool, script, or workflow capability |
| `fix:` | Bug fix in a script or workflow |
| `docs:` | README, CHANGELOG, or inline comment changes |
| `chore:` | Version bumps, dependency updates, housekeeping |

One logical change per PR. Keep commits atomic and the history readable.

---

## Running Acceptance Tests

**Locally (requires Tart):**
Expand All @@ -105,26 +91,3 @@ This boots a fresh Sequoia base image, runs `setup.sh` inside the VM, and execut
[VM Acceptance Test](../../actions/workflows/acceptance.yml) workflow.
The acceptance workflow also runs automatically on every `v*.*.*` release tag as part of the
release gate.

---

## Release Process

> Only the repo owner publishes releases.

Releases are handled by the `/publish-release` Claude Code skill, which automates the full flow:

1. Bumps version on `develop`, commits `chore: release v<version>`
2. Opens a PR: `develop → main`
3. Owner approves and merges the PR
4. Tags `main` with `v<version>` and pushes the tag
5. Release pipeline fires automatically: validate → VM acceptance → publish

To trigger manually:
```bash
# In Claude Code
/publish-release 1.0.0

# Or via bump script directly (then follow the steps above)
./scripts/bump-version.sh patch # or minor / major / set <version>
```
Loading