- All dependencies to current releases (97 known vulnerabilities -> 0), Python 3.14, uv pinned, requirements-test.txt, lxml/dateutil pinned - CSRF tokens on admin forms, logout and IndieAuth consent - IndieAuth client and crosspost link-card fetches via safe_get - FLASK_DEBUG/FLASK_ENV default off/production; image sets them - Foreign keys enforced on pooled connections; migration 018 removes orphans - Rate limits shared across processes (rate_limits, migration 019) - datetime.utcnow() and sqlite3 default adapters replaced - compose.yaml fixed; duplicate dev_auth.py and test.ini removed Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.7 KiB
Git Branching and Release Process
Status: Active Last Updated: 2026-11-03 (v2.10.1)
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
mainis 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-ffsomainshows one merge per release. - Every release is an annotated
vX.Y.Ztag onmain. 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 |
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.pyand 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-DDentry at the top ofCHANGELOG.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 - Full test suite passes:
SESSION_SECRET=test uv run pytest
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:
- builds the Containerfile
teststage, which runs the whole pytest suite; a failure stops the workflow and nothing is published; - builds the runtime image and pushes
git.thesatelliteoflove.com/phil/starpunk:vX.Y.Zand: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:
- If the release has a migration, back up the production database first (see architecture/deployment.md). Migrations run automatically when the new container starts.
- In the deployment repository, set
starpunk_versionto the new tag and deploy thestarpunkservice. - Check
/health, the home page, admin login and the feature that changed.
Migrations
- Files are
migrations/NNN_description.sql, numbered sequentially.starpunk/migrations.pyapplies the pending ones at startup and records them inschema_migrations. - Every gunicorn worker runs the migration check at startup; a
BEGIN IMMEDIATElock makes one worker apply them while the others wait. Since v2.8.1 the statements run withconn.executeinside that transaction. Don't useexecutescript()(it commits and drops the lock) and don't putBEGIN/COMMITin 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
- versioning-strategy.md: choosing the version number
- version-implementation-guide.md: where the version lives, changelog and design note format
- testing-checklist.md: tests and CI
- ADR-009: Git branching strategy