84 lines
4.0 KiB
Markdown
84 lines
4.0 KiB
Markdown
|
# 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>\"
|
|||
|
|
}" \
|
|||
|
|
"https://vulcan.apophisnetworking.net/api/v4/projects/jramos%2Fcve-dashboard/releases"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### GitLab Release creation details
|
|||
|
|
|
|||
|
|
- The GitLab instance is `https://vulcan.apophisnetworking.net`
|
|||
|
|
- Project path: `jramos/cve-dashboard` (URL-encoded: `jramos%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.
|