Files
StarPunk/docs/standards/git-branching-strategy.md
T
PhilandClaude Opus 5.5 ceef048003 docs: documentation review for v2.14.0
Architecture, README, standards, CLAUDE.md, settings reference, indexes,
backlog, release plans and CHANGELOG checked against the code at v2.14.0:
backfeed, notifications, counts line and web actions documented; test
policy (changed area locally, full suite in CI); stale versions, statuses
and links fixed; legacy and superseded docs moved.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 14:51:57 -07:00

6.9 KiB

Git Branching and Release Process

Status: Active Last Updated: 2026-11-10 (v2.14.0)

How changes reach main, how releases are cut, and what happens after a tag is pushed. This is the flow used for the v2 releases (see git log --merges). Which version number to use is in versioning-strategy.md. The original reasoning is in ADR-009; where they differ, this document describes current practice.

Principles

  • main is always releasable and is never rewritten or force-pushed.
  • Each release is built on its own short-lived branch, usually as a single commit, and merged with --no-ff so main shows one merge per release.
  • Every release is an annotated vX.Y.Z tag on main. The tag is what triggers CI; CI is what publishes the image.
  • Several agents may work on the repository at once, so each works in its own git worktree, never in the main checkout's working tree.

Branches

Prefix Use Example
feat/ new behaviour (MINOR) feat/v2.10.0-websub
fix/ bug and security fixes (PATCH) fix/v2.10.1-websub-hardening
ci/ build and CI changes ci/v2.7.1-pytest
chore/ maintenance, removals, licensing chore/remove-metrics
docs/ documentation only, no release docs/refresh-v2.10.1

Release branches are named <prefix>/vX.Y.Z-<short-description>, so the branch already states the version it will become. (Releases before v2.6.0 used feature/; read old history with that in mind.) There are no long-lived develop, release/ or hotfix/ branches: a production fix is just the next PATCH release from main.

Commits

Conventional-commit style subject, with the version in parentheses on the release commit:

feat: WebSub with a built-in hub (v2.10.0)
fix: Hold the migration lock for the whole run (v2.8.1)
ci: Run the test suite before building release images (v2.7.1)
docs: ADR-071 WebSub publishing with a built-in hub (proposed)

Types in use: feat, fix, ci, docs, style, refactor, test, chore. The body explains why, not what. Commits made by an agent end with the attribution trailer the agent was given.

An ADR can land on main ahead of its implementation (docs: commit, status "Proposed"), as ADR-071 did before v2.10.0.

Release process

1. Branch in a worktree

cd ~/Documents/projects/StarPunk                 # main checkout, on main
git pull
git worktree add ../StarPunk-worktrees/v2.10.1 -b fix/v2.10.1-websub-hardening main
cd ../StarPunk-worktrees/v2.10.1
uv venv --python 3.14 && uv pip install -r requirements-dev.txt

2. Make the change

Code, tests and docs together:

  • Code and tests (see testing-checklist.md)
  • Schema change? Add the next numbered file in migrations/ (see Migrations)
  • New setting? Read it in starpunk/config.py and document it in .env.example
  • Architectural decision? New ADR in docs/decisions/, or an "Amendments" section on the existing one
  • Bump the version in starpunk/__init__.py: both __version__ and __version_info__ (version-implementation-guide.md)
  • Add a ## [X.Y.Z] - YYYY-MM-DD entry at the top of CHANGELOG.md
  • Add a design note docs/design/vX.Y.Z/YYYY-MM-DD-<topic>.md (what changed and why, how it was verified). Small releases fully covered by an ADR amendment and the changelog may skip it
  • Tests for the changed area pass locally, e.g. SESSION_SECRET=test uv run pytest tests/test_notifications.py; CI runs the full suite on the tag (step 4)

Commit (usually one commit):

git add -A
git commit -m "fix: WebSub hardening from the adversarial review (v2.10.1)"

3. Merge, tag, push

From the main checkout:

cd ~/Documents/projects/StarPunk
git checkout main && git pull
git merge --no-ff fix/v2.10.1-websub-hardening \
    -m "Merge branch 'fix/v2.10.1-websub-hardening' for v2.10.1 release"
git tag -a v2.10.1 -m "v2.10.1: WebSub hardening"
git push origin main v2.10.1

Then remove the worktree and branch:

git worktree remove ../StarPunk-worktrees/v2.10.1
git branch -d fix/v2.10.1-websub-hardening

Merging to main, tagging and pushing are release actions: an agent does them only when the project owner has asked for the release.

4. CI builds the image

Pushing a tag that matches v[0-9]+.[0-9]+.[0-9]+ runs .gitea/workflows/build-container.yml on the Gitea runner:

  1. builds the Containerfile test stage, which runs the whole pytest suite; a failure stops the workflow and nothing is published;
  2. builds the runtime image and pushes git.thesatelliteoflove.com/phil/starpunk:vX.Y.Z and :latest.

Pre-release tags such as v2.0.0-rc.1 don't match the pattern and are not built by CI. The workflow can also be started by hand (workflow_dispatch).

If CI fails, fix it on a new branch and release the next PATCH version. Don't move or re-push an existing tag.

5. Deploy

Production is managed from the separate Ansible deployment repository, not from this one:

  1. If the release has a migration, back up the production database first (see architecture/deployment.md). Migrations run automatically when the new container starts.
  2. In the deployment repository, set starpunk_version to the new tag and deploy the starpunk service.
  3. Check /health, the home page, admin login and the feature that changed.

Migrations

  • Files are migrations/NNN_description.sql, numbered sequentially. starpunk/migrations.py applies the pending ones at startup and records them in schema_migrations.
  • Every gunicorn worker runs the migration check at startup; a BEGIN IMMEDIATE lock makes one worker apply them while the others wait. Since v2.8.1 the statements run with conn.execute inside that transaction. Don't use executescript() (it commits and drops the lock) and don't put BEGIN/COMMIT in migration files.
  • Migrations only move forward; there are no down migrations. The backup is the rollback.
  • Test a new migration against a copy of a database at the previous version.

See ADR-020, ADR-037 and docs/design/v2.8.1/2026-11-03-migration-lock.md.

Documentation-only changes

Branch docs/<description>, no version bump, no changelog entry, no tag. Merge with --no-ff like any other branch.

References