Manage semantic versioning, changelog generation, and release notes. Auto-generates entries from completed issues or git diff.
apm install @majiayu000/agent-ops-versioning
[](https://apm-p1ls2dz87-atlamors-projects.vercel.app/packages/@majiayu000/agent-ops-versioning)---
name: agent-ops-versioning
description: "Manage semantic versioning, changelog generation, and release notes. Auto-generates entries from completed issues or git diff."
category: docs
invokes: [agent-ops-state, agent-ops-git]
invoked_by: []
state_files:
read: [issues/history.md]
write: []
---
# Versioning & Release Management
## Purpose
Manage semantic versioning, generate changelogs from completed issues or git history, and coordinate releases.
## Input Sources
Changelog entries can be generated from multiple sources:
| Source | Command | Best For |
|--------|---------|----------|
| **Issues** (default) | `/agent-version bump minor` | Teams using issue-first workflow |
| **Git diff** | `/agent-version bump minor --from main` | Teams not using AgentOps issues |
| **Git tags** | `/agent-version bump minor --from v2.0.0` | Compare against specific release |
| **Hybrid** | `/agent-version bump minor --include-git` | Catch commits without issues |
## Semantic Versioning Rules
Follow [SemVer 2.0.0](https://semver.org/):
| Bump | When | Example |
|------|------|---------|
| **MAJOR** | Breaking changes, incompatible API changes | 1.0.0 → 2.0.0 |
| **MINOR** | New features, backward compatible | 1.0.0 → 1.1.0 |
| **PATCH** | Bug fixes, backward compatible | 1.0.0 → 1.0.1 |
### Pre-release Tags
- `-alpha.1` — Early development, unstable
- `-beta.1` — Feature complete, testing
- `-rc.1` — Release candidate, final testing
### Build Metadata
- `+build.123` — CI build number
- `+20260115` — Build date
## Operations
### 1. Version Bump
```
/agent-version bump {major|minor|patch} [--prerelease {alpha|beta|rc}]
```
**Procedure:**
1. Read current version from README.md badge or package.json
2. Calculate new version based on bump type
3. Scan `issues/history.md` for issues since last version tag
4. Generate changelog entries
5. Update files:
- CHANGELOG.md — Add new version section
- README.md — Update version badge and history table
- package.json (if exists) — Update version field
6. Suggest git tag command (never auto-create)
**Output:**
```
📦 Version Bump: 2.0.0 → 2.1.0
Changes detected (12 issues):
- Added: 5 features
- Fixed: 4 bugs
- Changed: 2 enhancements
- Security: 1 fix
Files to update:
- [x] CHANGELOG.md
- [x] README.md (badge + history)
- [ ] package.json (not found)
Preview CHANGELOG entry? [Y/n]
```
### 2. Changelog Generation
Auto-generate changelog entries from completed issues.
**Mapping issue types to changelog sections:**
| Issue Type | Changelog Section |
|------------|-------------------|
| `FEAT` | Added |
| `ENH` | Changed |
| `BUG` | Fixed |
| `SEC` | Security |
| `PERF` | Performance |
| `DOCS` | Documentation |
| `REFAC` | Changed |
| `CHORE` | Maintenance |
| `TEST` | Testing |
**Entry format:**
```markdown
### Added
- **FEAT-0042**: Add dark mode support ([details](issues/references/FEAT-0042.md))
- **FEAT-0038**: Implement OAuth login
### Fixed
- **BUG-0023**: Fix login timeout after 30s idle
- **BUG-0019**: Resolve null pointer in UserService
```
### 3. Release Notes
Generate user-friendly release notes (less technical than changelog).
```
/agent-version release-notes
```
**Output format:**
```markdown
# Release Notes: v2.1.0
## 🎉 What's New
### Dark Mode
You can now switch to dark mode! Go to Settings → Appearance → Theme.
### OAuth Login
Sign in with Google or GitHub for faster access.
## 🐛 Bug Fixes
- Fixed an issue where sessions would timeout too quickly
- Resolved crashes on the user profile page
## 🔒 Security
- Updated authentication to prevent session hijacking
---
*Full technical changelog: [CHANGELOG.md](CHANGELOG.md)*
```
### 4. Version Validation
Check that versions are consistent across files.
```
/agent-version check
```
**Validates:**
- README.md badge matches CHANGELOG.md latest version
- package.json version matches (if exists)
- Git tags exist for released versions
- No unreleased issues in history older than 30 days
**Output:**
```
✅ Version Check
Current: v2.0.0
- README.md badge: ✅ 2.0.0
- CHANGELOG.md latest: ✅ 2.0.0
- package.json: ⚠️ not found
- Git tag v2.0.0: ✅ exists
Unreleased issues: 3 (since 2026-01-10)
Suggestion: Consider v2.0.1 or v2.1.0 release
```
### 5. What's Unreleased
Show issues completed since last release.
```
/agent-version unreleased
```
**Output:**
```
📋 Unreleased Changes (since v2.0.0)
Added:
- FEAT-0045: Add export to PDF
- FEAT-0044: Implement search filters
Fixed:
- BUG-0048: Fix date picker timezone issue
Suggested version: 2.1.0 (new features, no breaking changes)
```
### 6. Changelog from Git Diff
Generate changelog entries from git commits between branches or tags.
```
/agent-version from-git {base} [target]
```
**Examples:**
```bash
/agent-version from-git main # Compare current branch to main
/agent-version from-git v2.0.0 # Compare HEAD to tag v2.0.0
/agent-version from-git main feature/xyz # Compare two branches
/agent-version from-git v1.0.0 v2.0.0 # Compare two tags
```
**Procedure:**
1. Run `git log {base}..{target} --oneline`
2. Parse commit messages using conventional commits format
3. Group by type (feat, fix, chore, etc.)
4. Generate changelog entries
5. Flag commits without conventional format for manual review
**Conventional Commit Parsing:**
| Commit Prefix | Changelog Section |
|---------------|-------------------|
| `feat:` `feat(scope):` | Added |
| `fix:` `fix(scope):` | Fixed |
| `docs:` | Documentation |
| `perf:` | Performance |
| `refactor:` | Changed |
| `chore:` | Maintenance |
| `test:` | Testing |
| `BREAKING CHANGE:` | ⚠️ Breaking |
**Output:**
```
📋 Git Diff Analysis: main..HEAD (23 commits)
Parsed (conventional commits):
- feat: 5 commits → Added
- fix: 8 commits → Fixed
- chore: 4 commits → Maintenance
- docs: 2 commits → Documentation
Unparsed (needs manual review):
- "Update stuff" (abc1234)
- "WIP" (def5678)
- "misc fixes" (ghi9012)
Suggested version: MINOR (new features detected)
Generate changelog from these? [Y/n]
```
**Hybrid Mode:**
Combine issues and git for comprehensive changelog:
```
/agent-version bump minor --include-git
```
1. Start with issues from `history.md`
2. Run git diff to find additional commits
3. Flag commits that don't have matching issues
4. User reviews and approves additions
```
📋 Hybrid Changelog Generation
From issues (12 entries):
- FEAT-0045: Add export to PDF
- BUG-0048: Fix date picker issue
...
From git (not in issues):
⚠️ 3 commits found without matching issues:
- abc1234: feat: add keyboard shortcuts
- def5678: fix: resolve memory leak
- ghi9012: chore: update dependencies
Include these in changelog? [A]ll / [S]elect / [N]one
```
## Version File Locations
| File | Version Location |
|------|------------------|
| README.md | Badge: `` |
| CHANGELOG.md | Header: `## [X.Y.Z] - YYYY-MM-DD` |
| package.json | Field: `"version": "X.Y.Z"` |
| pyproject.toml | Field: `version = "X.Y.Z"` |
| Cargo.toml | Field: `version = "X.Y.Z"` |
| *.csproj | Tag: `<Version>X.Y.Z</Version>` |
## Changelog Format
Follow [Keep a Changelog](https://keepachangelog.com/):
```markdown
# Changelog
## [Unreleased]
## [2.1.0] - 2026-01-20
### Added
- New feature X
### Changed
- Updated feature Y
### Deprecated
- Feature Z will be removed in 3.0.0
### Removed
- Deleted legacy API
### Fixed
- Bug in feature W
### Security
- Patched vulnerability in auth
```
## Git Tag Suggestions
After version bump, suggest (never auto-execute):
```
Suggested commands:
git add CHANGELOG.md README.md
git commit -m "chore: release v2.1.0"
git tag -a v2.1.0 -m "Release v2.1.0"
git push origin main --tags
Create these commits/tags? This will invoke agent-ops-git.
```
## Integration
- **agent-ops-git**: Coordinates commit and tag creation
- **agent-ops-report**: Can include version in reports
- **agent-ops-housekeeping**: Warns about stale unreleased changes