ccs/docs/version-management.md

Version Management

Overview

CCS uses semantic-release for fully automated versioning and releases. Version numbers are determined automatically from conventional commit messages - no manual version bumping required.

Release Channels

Branch	npm Tag	Example	Description
main	@latest	5.1.0	Stable production releases
dev	@dev	5.1.0-dev.1	Pre-release testing

How Releases Work

Automatic Release (Default)

1. Write conventional commits during development
2. Merge PR to main (or push to dev)
3. CI automatically:
   • Analyzes commits to determine version bump
   • Updates CHANGELOG.md
   • Updates VERSION, package.json, installers
   • Creates git tag
   • Publishes to npm
   • Creates GitHub release

Conventional Commits

Version bump is determined by commit type:

Commit Type	Version Bump	Example
feat:	MINOR	5.0.2 → 5.1.0
fix:	PATCH	5.0.2 → 5.0.3
perf:	PATCH	5.0.2 → 5.0.3
feat!: or BREAKING CHANGE:	MAJOR	5.0.2 → 6.0.0
docs:, style:, refactor:, test:, chore:, ci:	No release	-

Commit Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Examples:

feat(cliproxy): add OAuth token refresh
fix(doctor): handle missing config gracefully
feat!: remove deprecated GLMT proxy
docs: update installation guide

Workflow Examples

Stable Release

# 1. Work on feature branch
git checkout -b feat/new-feature
git commit -m "feat(scope): add new feature"

# 2. Open PR to main
gh pr create --base main

# 3. Merge PR → CI auto-releases to npm @latest

Dev Release

# 1. Switch to dev branch
git checkout dev
git merge feat/experimental

# 2. Push → CI auto-releases to npm @dev
git push origin dev

Installing Different Channels

# Stable (default)
npm install -g @kaitranntt/ccs

# Dev
npm install -g @kaitranntt/ccs@dev

# Specific version
npm install -g @kaitranntt/ccs@5.1.0-dev.1

Version Files

These files are automatically synced by semantic-release:

File	Purpose
VERSION	Shell scripts, runtime display
package.json	npm package version
installers/install.sh	Standalone bash installer
installers/install.ps1	Standalone PowerShell installer
CHANGELOG.md	Auto-generated release notes

Local Commit Validation

Commits are validated locally via husky + commitlint:

# This will be rejected:
git commit -m "added new feature"

# This will pass:
git commit -m "feat: add new feature"

Emergency Manual Release

For emergencies only (e.g., CI broken, hotfix needed):

./scripts/bump-version.sh patch
git add -A
git commit -m "chore(release): emergency release"
git push origin main
npm publish

Tooling

Tool	Purpose
semantic-release	Automated versioning and publishing
@semantic-release/changelog	Auto-update CHANGELOG.md
@semantic-release/git	Commit version files back
commitlint	Validate commit message format
husky	Git hooks for local validation

Configuration Files

• .releaserc.json - semantic-release configuration
• commitlint.config.cjs - commit message rules
• .husky/commit-msg - commit validation hook
• .github/workflows/release.yml - CI release workflow

Troubleshooting

Commit rejected by commitlint

# Check what's wrong
bunx commitlint --edit

# Fix commit message format
git commit --amend

No release triggered

Check if commits include releasable types (feat:, fix:, perf:). Documentation-only commits (docs:) don't trigger releases.

Dev out of sync with main

git checkout dev
git rebase main
git push --force-with-lease origin dev