---
roadcrew_template_name: "tag-release.md"
roadcrew_template_type: "command"
execution_mode: "auto-execute"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-25"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
---

# /tag-release

Manage version releases with strict semantic versioning and automated release notes.

**Tier:** FREE  
**Pattern:** PUBLISH (Distribution & Customer Support)  
**Related:** Epic #146, Issue #149

## What It Does

1. **Analyze Commits:** Parse git history since last tag
2. **Detect Changes:** Identify breaking changes, features, fixes
3. **Suggest Bump:** Recommend major/minor/patch based on commits
4. **Update Version:** Bump package.json version
5. **Create Release:** Tag commit and create GitHub release

## Usage

```bash
# Auto-detect bump type (recommended)
/tag-release --auto

# Manual bump type selection
/tag-release --major    # Breaking changes (v1.0.0 → v2.0.0)
/tag-release --minor    # New features (v1.0.0 → v1.1.0)
/tag-release --patch    # Bug fixes (v1.0.0 → v1.0.1)

# Preview without committing
/tag-release --major --dry-run
```

## Workflow

**Step 1: Analyze Commits**
- Get current version from package.json
- Find last tag in git history
- Parse commits between last tag and HEAD

**Step 2: Detect Changes**
- Look for breaking change indicators:
  - Commit message: "BREAKING CHANGE:"
  - Commit type: "feat!" or "fix!"
- Look for features: "feat:" prefix
- Look for fixes: "fix:" or "patch:" prefix

**Step 3: Suggest Bump**
- If breaking changes found: suggest --major
- Else if features found: suggest --minor
- Else: suggest --patch

**Step 4: Confirm & Update**
- Show current version and new version
- Update package.json version
- Generate release notes from commits

**Step 5: Create Tag & Release**
- Create annotated git tag with version
- Push tag to GitHub
- Create GitHub release with auto-generated notes
- Include commit list in release body

## Implementation Notes

**Key Functions:**
- `parseGitCommits()` - Get commits since last tag
- `detectBreakingChanges()` - Analyze for breaking changes
- `suggestBumpType()` - Recommend major/minor/patch
- `calculateNextVersion()` - Semantic version math
- `generateReleaseNotes()` - Format commit list
- `createGitTag()` - Git tagging operation
- `createGitHubRelease()` - GitHub release creation

**Semantic Versioning Rules:**
- MAJOR: Breaking changes (incompatible API changes)
- MINOR: New features (backward compatible)
- PATCH: Bug fixes (backward compatible)
- Format: v{MAJOR}.{MINOR}.{PATCH}

**Commit Parsing:**
```
feat: New feature → MINOR bump
fix: Bug fix → PATCH bump
refactor: Code refactoring → PATCH bump
BREAKING CHANGE: Breaking change → MAJOR bump
feat!: Feature with breaking change → MAJOR bump
```

## Success Criteria

- ✅ Commits analyzed correctly
- ✅ Bump type detected accurately
- ✅ Version calculation follows semver strictly
- ✅ package.json updated with new version
- ✅ Git tag created and pushed
- ✅ GitHub release created with notes
- ✅ Release notes include commit summary

## Related

- See Epic #146 for full PUBLISH pattern
- Depends on: Issue #147 (dist-builder), Issue #148 (build-validator)
- Pairs with: /publish-distribution for full workflow
- Used by: /update-roadcrew-customer for versioning