# 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:
   ```bash
   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):
   ```bash
   # 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.