This skill should be used when automating mandatory checks and deliverables
docs/deliverables/<version>/ with links in docs/home.md| File | Purpose | Load When |
|---|
references/pr-steps-deliverables.md | Before/after PR steps, inputs/triggers, required checks, artifact directory layout | Executing PR automation or reviewing compliance |
references/templates-version-bump.md | CHANGELOG template, release notes template, SemVer bump logic | Generating versioning artifacts |
BEFORE MERGE (8 steps):
1. Compute version bump (MAJOR/MINOR/PATCH) → update version file
2. Generate/update CHANGELOG.md → commit + copy to wiki
3. Generate release notes → save to docs/deliverables/<version>/
4. Update specifications → docs/specs/
5. Run tests + store reports → docs/deliverables/<version>/test-reports/
6. Static analysis + security scan → docs/deliverables/<version>/analysis/
7. Generate SBoM + license review → docs/deliverables/<version>/sbom/
8. Commit and push all changes
AFTER MERGE (3 steps):
1. Delete source branch → log to docs/deliverables/branches/deletions.log
2. Archive all artifacts and mark PR as fully delivered
3. Create git tag on main: vMAJOR.MINOR.PATCH
The version number in CHANGELOG.md section headers MUST be computed using gitversion (GitVersion tool) — never hardcoded or manually guessed.
# Compute SemVer from current branch/commit (gitversion is pre-installed in the agent image)
gitversion /showvariable SemVer
# → 1.3.0
# Full version info (JSON output)
gitversion
# → { "Major": 1, "Minor": 3, "Patch": 0, "SemVer": "1.3.0", "FullSemVer": "1.3.0+42", ... }
# Azure DevOps pipeline
- script: |
VERSION=$(gitversion /showvariable SemVer)
echo "##vso[build.updatebuildnumber]$VERSION"
displayName: 'Compute SemVer with GitVersion'
# GitHub Actions
- name: Compute version
id: version
run: echo "SEMVER=$(gitversion /showvariable SemVer)" >> "$GITHUB_OUTPUT"
# GitLab CI
compute_version:
script:
- export SEMVER=$(gitversion /showvariable SemVer)
- echo "Version: $SEMVER"
# Jenkins (Declarative Pipeline)
environment {
SEMVER = sh(script: 'gitversion /showvariable SemVer', returnStdout: true).trim()
}
## [${SEMVER}] - YYYY-MM-DD ← version from gitversion, date = today
### Added
- ...
The [Unreleased] section is promoted to [${SEMVER}] at PR/release time using the gitversion-computed value.
Artifact root: docs/deliverables/<version>/
Required before merge: CHANGELOG + release notes + specs update + test reports +
analysis reports + SBoM/licenses — all linked from docs/home.md
Blocking failures: missing/failing tests, coverage drop below threshold, critical/high vulnerabilities, hardcoded secrets, missing SBoM
Release notes rules: write for diverse audiences, include migration instructions for breaking changes, never minimize impact, cross-reference documentation