ADR 0043 — Application Versioning Strategy &ZeroWidthSpace;

Status: Accepted
Date: 2026-06-26
Deciders: Kristopher Turner
Supersedes: —
Related: ADR 0001 (monorepo structure), ADR 0030 (progressive feature enablement)
ADO: AB#4478

Context &ZeroWidthSpace;

The Heritage Community Hub monorepo ships three applications (web, API, mobile) and several shared packages. As of 2026-06-26 all apps still carry their initial 0.1.0 version despite 13+ feature milestones being delivered. There is no agreed policy for when or how versions change, no CHANGELOG, and no API versioning beyond the static /api/v1 URL prefix.

Decision &ZeroWidthSpace;

1. Application versions — Semantic Versioning (SemVer) &ZeroWidthSpace;

All three apps (@hch/web, @hch/api, @hch/mobile) share a single coordinated version following Semantic Versioning 2.0.0.

Version component	When to bump
MAJOR (`1.0.0`)	Reserved for post-MVP "stable release" or breaking platform restructuring. We are pre-1.0 (0.x).
MINOR (`0.x.0`)	A new user-facing feature epic is delivered. Examples: Listen portal, Homeschool portal, Marketplace.
PATCH (`0.x.y`)	Bug fixes, performance improvements, non-breaking refactors, dependency updates.

The version is bumped in all three apps/*/package.json files in the same commit as the feature's final merge to main.

2. Packages — independent versioning &ZeroWidthSpace;

packages/* follow their own SemVer, bumped only when the package API changes. The web/api/mobile app versions are not coupled to package versions.

3. API versioning — URL prefix strategy &ZeroWidthSpace;

The current URL prefix /api/v1 is stable for all non-breaking changes.
A new prefix /api/v2 is introduced only when breaking changes affect existing clients (field removals, response shape changes, auth contract changes).
Additive changes (new endpoints, new optional fields) do NOT require a version bump.
Both prefixes are supported simultaneously during a transition window of at least one minor app release.

4. CHANGELOG &ZeroWidthSpace;

CHANGELOG.md at the repo root tracks all public-facing changes per release, organized as:

## [0.x.y] — YYYY-MM-DD
### Added
### Fixed
### Changed
### Breaking

Updates to CHANGELOG.md are required in the same commit as the version bump.

5. Current version baseline &ZeroWidthSpace;

The version 0.9.0 reflects the following delivered milestones since the initial 0.1.0:

Version	Milestone
0.1.0	Platform scaffold, auth, member registration
0.2.0	Family portal, member profile extension
0.3.0	Calendar + Announcements
0.4.0	Groups + Ministries management
0.5.0	Community Marketplace
0.6.0	Homeschool Education Portal
0.7.0	Rideshare + Pony Express
0.8.0	Admin + Minister portals
0.9.0	Listen / Sermons & Music Hub (AB#3137)

Consequences &ZeroWidthSpace;

Developers must bump the version in all three apps/*/package.json files when merging an epic.
The version is visible to users in the /app/about page footer and in GET /api/v1/health.
No tooling automation (e.g., changesets) is required at this stage — manual bump is sufficient.
ADO work items track version-bump tasks alongside feature stories.