2.9 KiB
Versioning Strategy
Status: Active Last Updated: 2026-11-03 (v2.10.1)
StarPunk uses Semantic Versioning 2.0.0:
MAJOR.MINOR.PATCH, currently 2.13.2. Every release is a git tag
vX.Y.Z and a CHANGELOG.md entry. Where the number is stored and how to
write the changelog entry is in
version-implementation-guide.md; the
release steps are in git-branching-strategy.md.
Background: ADR-008.
What the number means
StarPunk is a single-user site, so "compatibility" means: can the owner upgrade by changing the image tag, without editing configuration, losing data, or breaking Micropub clients, feed readers and other sites that talk to it?
MAJOR: the owner has to act, or something that worked stops working.
- A required setting is added, renamed or removed, or login changes
(v2.0.0: IndieLogin replaced by OIDC admin login, new
OIDC_*settings) - A public URL, feed or protocol endpoint goes away or changes behaviour incompatibly
- Data has to be converted by hand
MINOR: new capability; upgrading needs no action.
- New features, post types, protocol support or crossposting targets (v2.6.0 Threads, v2.9.0 bookmarks, v2.10.0 WebSub)
- New optional settings with safe defaults
- Changes to defaults that a spec review shows are needed for compliance (v2.9.0: Micropub posts are only crossposted to targets the client asks for). Call these out under Changed in the changelog
PATCH: fixes; nothing new to learn.
- Bug and security fixes (v2.8.1 migration lock, v2.10.1 WebSub hardening)
- Spec-compliance fixes that don't add features
- CI and build changes (v2.7.1)
A migration on its own doesn't decide the level: migrations run automatically, so a PATCH may include one (v2.10.1 added migration 017). What it changes decides the level. Any release with a migration needs a database backup before deploying.
Decision guide
- Does upgrading require the owner to change configuration or data, or break an existing client or URL? MAJOR
- Otherwise, does it add something new (feature, endpoint, setting, post type)? MINOR
- Otherwise PATCH.
A MINOR resets PATCH to 0; a MAJOR resets both.
Pre-releases
Release candidate tags vX.Y.Z-rc.N may be used to try a risky release
in production first (v1.x had several; the last was v2.0.0-rc.1). CI only
builds tags matching vX.Y.Z, so a release candidate image has to be built
by hand. __version__ may carry the suffix ("1.1.1-rc.2");
__version_info__ holds the numbers only ((1, 1, 1)).
Documentation-only changes
No version change. They are merged on a docs/ branch without a tag.