Files
StarPunk/docs/standards/versioning-strategy.md
T

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.1. 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

  1. Does upgrading require the owner to change configuration or data, or break an existing client or URL? MAJOR
  2. Otherwise, does it add something new (feature, endpoint, setting, post type)? MINOR
  3. 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.

References