mirror of
https://github.com/tiennm99/ccs.git
synced 2026-07-16 18:16:08 +00:00
kaitranntt
9f40a0e255
Update CI/CD configuration, documentation, and scripts to use dev as the primary integration branch instead of beta. Changes include GitHub Actions workflow triggers, semantic-release configuration, and all relevant documentation and helper scripts.
173 lines
3.9 KiB
Markdown
173 lines
3.9 KiB
Markdown
# 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:**
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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):
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
git checkout dev
|
|
git rebase main
|
|
git push --force-with-lease origin dev
|
|
```
|