cve-dashboard/.kiro/steering/versioning.md

Versioning & Release Management

Version Numbering

This project uses Semantic Versioning (MAJOR.MINOR.PATCH) but with a practical cadence-based approach to avoid runaway patch numbers.

When to bump what

Change type	Bump	Example
Breaking change (new DB engine, incompatible API/config, data migration required)	MAJOR	2.0.0 → 3.0.0
New feature, new page, new integration, significant enhancement	MINOR	2.1.0 → 2.2.0
Bug fix, UI tweak, docs update, refactor with no user-visible change	PATCH	2.1.0 → 2.1.1

Cadence rules to keep numbers sane

• Bundle bug fixes into the next minor release rather than tagging a patch for every individual fix. Only cut a standalone patch release (x.y.Z) if a fix is urgent and needs to ship before the next feature is ready.
• One minor bump per feature batch — if a work session produces 2–3 features and 5 bug fixes, that's one minor release, not five patches and two minors.
• Tag releases at logical milestones, not per-commit. A good release boundary is: "a user would notice something new or different."
• Never exceed x.y.5 in patches before rolling into the next minor. If you're at x.y.5 and still shipping fixes, just bump to x.(y+1).0 and include the fixes there.

Practical workflow

1. Work on features and fixes on master as normal — no version bump per commit.
2. When a logical batch is complete (end of a sprint, feature area done, before a deploy you want to mark), decide the version:
   • Any breaking change since last tag? → MAJOR
   • Any new features? → MINOR
   • Only fixes? → PATCH (but prefer bundling into next MINOR)
3. Update CHANGELOG.md with the new version section.
4. Commit the changelog update.
5. Tag and push:

   git tag -a vX.Y.Z -m "vX.Y.Z — short summary"
   git push origin vX.Y.Z
   git push backup vX.Y.Z
   

6. Create a GitLab Release from the tag (renders changelog on the Releases page):

   # Extract the changelog section for this version from CHANGELOG.md
   # Then create the release via GitLab API:
   curl --silent --request POST \
     --header "PRIVATE-TOKEN: $GITLAB_PAT" \
     --header "Content-Type: application/json" \
     --data "{
       \"tag_name\": \"vX.Y.Z\",
       \"name\": \"vX.Y.Z\",
       \"description\": \"<changelog section in markdown>\"
     }" \
     "http://steam-gitlab.charterlab.com/api/v4/projects/steam%2Fcve-dashboard/releases"
   

GitLab Release creation details

• The GitLab instance is http://steam-gitlab.charterlab.com
• Project path: steam/cve-dashboard (URL-encoded: steam%2Fcve-dashboard)
• Auth: GITLAB_PAT from backend/.env
• The description field accepts full markdown — paste the relevant ## [vX.Y.Z] section from CHANGELOG.md
• The release appears under Deployments → Releases in the GitLab sidebar with rendered markdown, download archives, and a badge showing the latest version

What counts as a "breaking change"

• Database engine or schema change that requires migration with data transformation
• Removal or rename of API endpoints that external consumers depend on
• Environment variable changes that would break an existing deployment on pull
• Dropping support for a previously supported platform or runtime version

Adding new required env vars for new features is NOT breaking — existing features still work without them.

Release Suggestion Prompt

After completing work (features, fixes, or both), suggest the next version number based on:

1. What the last tagged version is (git tag -l --sort=-v:refname | head -1)
2. What changed since that tag (git log <last_tag>..HEAD --oneline)
3. The cadence rules above

Format the suggestion as:

Suggested release: vX.Y.Z Reason: [brief justification based on change types] Changelog entries to add: [bullet list of items to add]

Only suggest a release if there are meaningful user-visible changes. Internal refactors, test additions, and CI tweaks alone do not warrant a release.