Skip to main content

​
Branch Strategy

Each major version has its own long-lived branch. All development for that version happens on its branch.
BranchPurpose
0.xActive development for v0
1.xFuture v1 (created when v1.0.0 is released)
mainNot used for development

​
Semantic Versioning

Core follows semver:
  • Patch (0.x.Y) — bug fixes, no breaking changes
  • Minor (0.X.0) — new features, backwards compatible
  • Major (X.0.0) — breaking changes, upgrade guide required
The current version is tracked in version.txt and is bumped automatically by the release workflow.

​
Commit Messages

All commits must follow Conventional Commits. The pre-commit hook rejects non-conforming messages. 
type(scope): description
Allowed types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test 
feat(tables): add PropertyColumn sortability
fix: resolve pagination reset on filter change
docs: update authentication page
Body lines must not exceed 100 characters.

​
Creating a Release

Never create a release without explicit confirmation. Releases are irreversible and immediately affect all downstream projects.
# Preview what will happen — always run this first
bin/release.sh patch --dry-run

# Patch release (bug fixes)
bin/release.sh patch

# Minor release (new features)
bin/release.sh minor

# Major release (breaking changes)
bin/release.sh major
The script reads the current version from version.txt, shows what version will be created, and asks for confirmation before triggering the GitHub workflow.

​
Using GitHub CLI

gh workflow run publish_release.yml --ref 0.x -f version_type=patch
gh workflow run publish_release.yml --ref 0.x -f version_type=minor
gh workflow run publish_release.yml --ref 0.x -f version_type=major

​
Before Every Release

  1. Ensure all changes are committed and pushed
  2. For minor/major releases, update UPGRADE.md with migration instructions
  3. Run bin/release.sh patch --dry-run to preview
  4. Confirm the version is correct before proceeding

​
Starting a New Major Version

# Create the new branch from the current development branch
git checkout 0.x && git pull
git checkout -b 1.x
git push -u origin 1.x

# Trigger the major release from the new branch
bin/release.sh major
After releasing, update the default branch on GitHub to the new version branch.

​
Hotfixes for Older Versions

  1. Merge your fix into the old version branch (e.g., 0.x)
  2. Cut a patch release: bin/release.sh patch
  3. Cherry-pick to newer branches as needed