Piper Morgan Versioning Strategy

Two versioning docs, deliberately (clarified 2026-08-12): this one explains the release strategy — branch model, cut process, and the VERSION/pyproject must-match rule that scripts/check-version-consistency.py enforces. VERSION_NUMBERING.md explains the numbering scheme — what each tier of X.Y.Z means.

Current Version: 0.8.14.0 (released 2026-09-23; cut from `main` — `production` is retiring with the droplet, not advanced)

v0.8.14.0 was cut from main two days after v0.8.13.0 — the first release whose deploy target is the Fly-served alpha (cutover 2026-09-22); the production branch is deliberately NOT advanced (it retires with the droplet, cutover runbook step 11). Prior: v0.8.13.0 was cut from main (pyproject bumped there) and production fast-forwarded to the same commit — a one-day fast follow to v0.8.12.0 (2026-09-20), which had closed the two-month gap since v0.8.11.0 (2026-07-17). Releases cut from main; production tracks the released commit. (A real staged pipeline is being designed under Arch’s 09-20 tasking.)

Versioning Scheme

Piper Morgan follows Semantic Versioning (SemVer) with the following format:

MAJOR.MINOR.PATCH[-PRERELEASE]

Version Components

MAJOR: Incremented for incompatible API changes
MINOR: Incremented for backwards-compatible functionality additions
PATCH: Incremented for backwards-compatible bug fixes
PRERELEASE: Optional suffix for pre-release versions (alpha, beta, rc)

Current Versioning Strategy

Pre-1.0 (Alpha Phase)

0.x.y-alpha: Alpha releases leading to MVP
0.x.y-beta: Beta releases for final testing before MVP
1.0.0: First MVP release

Post-1.0 (Production)

1.x.y: Production releases following standard SemVer
2.0.0+: Major version increments for breaking changes

Version Sources of Truth

Primary Version Definition

VERSION file: Single source of truth in project root
pyproject.toml: Python package version (must match VERSION file)

Version References

Alpha documents: Reference current semantic version
API responses: Include version in metadata
Documentation: Version-specific guides and references

Roadmap vs. Version Separation

Important: Roadmap positions (e.g., “2.7.5”, “Sprint A8”) are separate from software versions.

Roadmap positions: Track project progress and sprint completion
Software versions: Track actual software releases and compatibility

This separation allows:

Flexible roadmap adjustments without version confusion
Clear software compatibility communication
Independent roadmap and release planning

Version Management

Manual Process (Current)

Update VERSION file
Update pyproject.toml version field
Update relevant documentation
Create git tag for releases

Future Automation (Planned)

Automated version bumping scripts
CI validation of version consistency
Automatic changelog generation
Integration with release workflows

Alpha Testing Versions

During alpha testing, versions follow this pattern:

0.8.0-alpha: Current alpha version
0.8.1-alpha: Bug fixes and minor improvements
0.9.0-alpha: New features and capabilities
1.0.0-beta: Beta testing before MVP
1.0.0: MVP release

Version History

Version	Date	Milestone	Notes
0.8.14.0	Sep 23, 2026	Fast follow	“On Your Clock” — preferences persist (#1574), user-zone clock faces + agenda TBD fixed (#1576 family), one-line add-project (#1856), honest 404-close (#1858), any-provider gate + four honest LLM-error sentences first deployed (#1823/#1824), preferences routes fixed (#1864); 13 dead modules + 5 tables removed
0.8.13.0	Sep 21, 2026	Fast follow	Dogfood fixes — standup trust rebuild (#1837/#1836), keyless first contact (#1818b), server-key concept deleted (#1812 complete), /health deploy identity (#1839)
0.8.12.0	Sep 20, 2026	Feature	“Your Key, Your Account” — BYOC end to end, honest keyless refusals, security six, acceptance contract; first full-belt-green cut (row added 09-21; missed at the 09-20 cut)
0.8.11.0	Jul 17, 2026	Feature	Finish-the-Unfinished sprint — multi-tenancy correctness, honest conversation, completion ratchets (#1424/#1419); migrations j1394ledger + k1422prefs
0.8.10.x	Jul 8–16, 2026	Dot train	production-only tester-loop cuts (.1–.14): Fly beta cutover, per-user LLM keys page, login regression fix
0.8.9.2	Jul 2026	Patch	Security fix (#1344) — open-registration exposure closed, invite-token gate (hotfix on `production`)
0.8.9.1	Jul 2026	Patch	Security fix (#1343) — anonymous LLM-key billing exposure closed (hotfix on `production`)
0.8.9	Jun 2026	RECONNECT	RECONNECT WS-1 + security + design D2 — connector infra, field encryption, token system
0.8.8	Jun 2026	RECONNECT	D1/RECONNECT — BYOC keys, Radar default, nav IA, home UX
0.8.7	Jun 2026	M1+M2+M3	Conscious Floor, dispatch rail complete, files UX, Slack inbound
0.8.6	Mar 2026	M0 Sprint	M0 Conversational Glue, 27 issues resolved
0.8.5.3	Feb 2026	Patch	Windows compatibility, setup UX, 14 issues resolved
0.8.5.2	Feb 2026	Patch	Chat persistence, date formatting, calendar fixes
0.8.5.1	Jan 2026	Patch	14 alpha testing bug fixes
0.8.5	Jan 2026	MUX	MUX-IMPLEMENT complete, WCAG 2.1 AA accessibility
0.8.4.3	Jan 2026	Sprint A20	Fresh install fixes (#605-#609), UI polish
0.8.4.2	Jan 2026	Sprint A20	Calendar bug fixes (#596, #588)
0.8.4.1	Jan 2026	Sprint A20	Calendar/TEMPORAL timezone fixes
0.8.4	Jan 2026	Sprint B1	Integration Settings, Portfolio Onboarding
0.8.3.2	Jan 2026	Sprint B1	Interactive Standup Assistant (Epic #242)
0.8.3.1	Jan 2026	Sprint B1	FTUX improvements
0.8.3	Jan 2026	Sprint A17	Epic #314 CONV-UX-PERSIST complete
0.8.2	Dec 2025	Sprint A13	UX polish, accessibility improvements
0.8.1	Nov 2025	Sprint A9	Bug fixes and improvements from alpha testing
0.8.0	Oct 2025	Sprint A8	Alpha tester onboarding preparation
1.0.0	TBD	MVP	Target MVP release

Guidelines for Contributors

Never tie versions to roadmap positions
Update VERSION file first, then pyproject.toml
Use semantic versioning principles
Document breaking changes clearly
Test version references in documentation

Last updated: July 3, 2026 Current version: 0.8.9.2 (released) — main at 0.8.9 pending next cut