Version

Version Management

Universal release version management using Semantic Versioning (SemVer) with auto-detection, Keep a Changelog format, and git integration.

Versioning Schemes

Semantic Versioning (Default)

Format: MAJOR.MINOR.PATCH (e.g., 1.2.3)

Pre-release: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1

Calendar Versioning (CalVer)

Format: YYYY.MM.DD or YYYY.MM.PATCH (e.g., 2026.01.30)

Use when: Release cadence matters more than compatibility tracking.

Workflow

1. Auto-Detect Version Locations

Scan repository for version declarations:

Also check:

• UI version displays (search for version in .tsx, .vue, .svelte files)
• Docker files (Dockerfile, docker-compose.yml)
• CI/CD configs (.github/workflows/*.yml, azure-pipelines.yml)

2. Present Detected Locations

## Version Locations Detected

| # | File | Current Version | Line | Action |
|---|------|-----------------|------|--------|
| 1 | package.json | 1.2.3 | 3 | Y/n |
| 2 | admin/package.json | 1.2.3 | 3 | Y/n |
| 3 | src/version.ts | 1.2.3 | 5 | Y/n |
| 4 | CHANGELOG.md | 1.2.3 | 7 | Y/n |

**Add more locations?** Enter file paths or press Enter to continue:

3. Determine Version Bump

Ask user:

Current version: 1.2.3

What type of release?
1. PATCH (1.2.4) - Bug fixes only [recommended for most releases]
2. MINOR (1.3.0) - New features, backward compatible
3. MAJOR (2.0.0) - Breaking changes
4. Custom - Enter specific version

Enter choice (1-4) or version number:

4. Update CHANGELOG.md

Enforce Keep a Changelog format (https://keepachangelog.com):

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.3.0] - 2026-01-30

### Added
- New feature X

### Changed
- Updated behavior Y

### Fixed
- Bug fix Z

### Removed
- Deprecated feature W

## [1.2.3] - 2026-01-15
...

Changelog sections (use only what applies):

• Added - New features
• Changed - Changes in existing functionality
• Deprecated - Soon-to-be removed features
• Removed - Removed features
• Fixed - Bug fixes
• Security - Vulnerability fixes

If CHANGELOG.md doesn't exist, create it with proper header.

5. Git Integration

After updating files, offer:

## Git Integration

| # | Action | Command | Recommended |
|---|--------|---------|-------------|
| 1 | Stage changes | git add -A | Y/n |
| 2 | Commit | git commit -m "chore: bump version to 1.3.0" | Y/n |
| 3 | Create tag | git tag -a v1.3.0 -m "Release 1.3.0" | Y/n |
| 4 | Push with tags | git push && git push --tags | y/N |

Enter numbers to SKIP or press Enter to apply recommended:

6. Generate Release Notes (Optional)

If git history available, offer to generate release notes from commits:

# Get commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

Format for GitHub/GitLab releases:

## What's Changed

### Features
- feat: Add new dashboard widget (#123)
- feat: Support dark mode (#124)

### Bug Fixes
- fix: Resolve memory leak (#125)
- fix: Correct date formatting (#126)

**Full Changelog**: https://github.com/owner/repo/compare/v1.2.3...v1.3.0

Pre-Release Checklist

Before bumping version:

• All tests passing
• CHANGELOG.md updated with changes
• No uncommitted changes (or commit them first)
• On correct branch (main/master)

Version Inconsistency Detection

If different files have different versions, flag immediately:

⚠️ Version Inconsistency Detected!

| File | Version |
|------|---------|
| package.json | 1.2.3 |
| admin/package.json | 1.0.0 | ← MISMATCH
| src/constants.ts | 1.2.2 | ← MISMATCH

Recommendation: Align all versions to 1.2.3 before proceeding.
Continue anyway? (y/N)

Output Format

# Version Bump Summary

**Repository**: {repo-name}
**Previous**: {old-version}
**New**: {new-version}
**Type**: {MAJOR|MINOR|PATCH}

## Files Updated

| File | Old | New | Status |
|------|-----|-----|--------|
{rows}

## Git Actions

| Action | Status |
|--------|--------|
| Staged | ✅ |
| Committed | ✅ |
| Tagged | ✅ |
| Pushed | ⏭️ Skipped |

---

Next: Push when ready with `git push && git push --tags`

"Version numbers are a communication tool, not a marketing tool."

Converted and distributed by TomeVault — claim your Tome and manage your conversions.