a61d254ff9
New specs: archer-template-library, ccp-metrics-view-restructure, compliance-list-stale-after-sidebar-edit, compliance-metric-estimated-resolution-date, compliance-remediation-display-fix, flexible-jira-ticket-creation, forecast-burndown-chart, granite-loader-export, ivanti-queue-clear-completed-fix, multi-item-jira-ticket, queue-collapsible-sections, vendor-issue-type-dropdown New steering: archer-template-gen.md Updated: migration-registration-check hook, remediation-plan-history spec, gitlab-workflow, tech, versioning steering files
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>\"
|
||
}" \
|
||
"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.
|