Versioning: SemVer, changelog, tags

Semantic Versioning

The project follows Semantic Versioning (SemVer):

• MAJOR (X.0.0): Incompatible API changes
• MINOR (0.X.0): New functionality, backwards-compatible
• PATCH (0.0.X): Backwards-compatible bug fixes

Every release updates three things together:

• The package.json version field
• CHANGELOG.md (Keep a Changelog format)
• A git tag (e.g. v0.1.0) that backs a GitHub Release

What constitutes a version bump

The whole point of the RBAC rows: because the capability matrix is a public contract of the kit, silently changing it is a compatibility event — hence the MAJOR bumps. A real billing adapter is a headline feature, so it lands as a MINOR. Everything small and safe is a PATCH.

How to pick a version

1. Changelog: CHANGELOG.md — every released version is documented there, newest first. The public repo carries no git tags and no GitHub Releases by design: version tags and Releases are created only on the private repository, so a buyer's version can be pinned for support without publishing anything attributable.
2. Clone a specific tag:

   git clone https://github.com/verdantstack/sveltekit-supabase-starter.git

3. Download a specific version:

   curl -L https://github.com/verdantstack/sveltekit-supabase-starter/archive/refs/tags/v0.3.3.zip -o starter-v0.3.3.zip

Changelog format

The changelog follows Keep a Changelog, with the conventional section order:

## [version] - YYYY-MM-DD

### Added
- New features

### Changed
- Changes to existing functionality

### Deprecated
- Features that will be removed

### Removed
- Removed features

### Fixed
- Bug fixes

### Security
- Vulnerability fixes

Version history

Production checklist

• Follow Semantic Versioning: MAJOR for incompatible API changes, MINOR for new backwards-compatible features, PATCH for bug fixes.
• Update package.json, CHANGELOG.md (Keep a Changelog), and a git tag on every release.
• Bump MAJOR on any breaking change to the RBAC matrix (removing a permission, changing the role hierarchy).
• Bump MINOR for new features such as a real billing adapter.
• Bump PATCH for bug fixes, documentation updates, and non-breaking dependency upgrades.
• Point buyers at the GitHub Releases page and teach them to clone or download a specific tagged version.

All six lines are implemented in the starter kit, and the release artifacts live at CHANGELOG.md. See the testing guide for how the suite stays green before a release is cut.