Guide
Versioning: SemVer, changelog, tags
A version number is a promise about compatibility, and a changelog is the receipt. Our SvelteKit + Supabase Starter follows Semantic Versioning and Keep a Changelog so buyers of the starter know exactly what a version bump means — and can pin a specific release. This guide is the versioning contract for the project.
Status: the current release is 0.1.0, the initial release on 2026-08-29 — Supabase RLS, RBAC, invites, seat billing, and the audit log. Everything below is how later versions get chosen.
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.jsonversion 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
| Change Type | Bump | Example |
|---|---|---|
| Breaking change to RBAC matrix | MAJOR | Removing a permission, changing role hierarchy |
| New feature (e.g., real billing adapter) | MINOR | Adding a billing adapter, new API endpoint |
| Bug fix (e.g., invite handling) | PATCH | Fixing behavior without API changes |
| Documentation updates | PATCH | Adding docs, fixing typos |
| Dependency updates (non-breaking) | PATCH | Upgrading the Supabase client |
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
- GitHub Releases page: https://github.com/verdantstack/sveltekit-supabase-starter/releases — each release has a tag (e.g.
v0.1.0) and release notes fromCHANGELOG.md. - Clone a specific tag:
git clone --branch v0.2.1 https://github.com/verdantstack/sveltekit-supabase-starter.git - Download a specific version:
curl -L https://github.com/verdantstack/sveltekit-supabase-starter/archive/refs/tags/v0.2.1.zip -o starter-v0.2.1.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 fixesVersion history
| Version | Date | Summary |
|---|---|---|
0.1.0 | 2026-08-29 | Initial release: Supabase RLS, RBAC, invites, seat billing, audit log |
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 GitHub Releases. See the testing guide for how the suite stays green before a release is cut.
Related reading
- Testing — the gate that keeps a release green
- Seat billing — the MINOR-worthy feature scheduled for a real adapter
- Architecture — the design that a MAJOR RBAC change would alter
- Product page — features, pricing, FAQ
- All documentation — guides, deep dives, and evaluations
Get in touch
Questions about the product, team licenses, or anything else? We'll respond within 48 hours.