# Release

> Release process for mdvs. Use when the user asks to make a release (patch, minor, major, or release candidate).

- Skill: `majiayu000/release-8` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/release-8`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/release-8/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/release-8

---


# Release Process

Releases go through a branch + PR (because main is protected), then a tag push triggers the GitHub Actions release workflow (`cargo-dist`) that builds cross-platform binaries and creates a GitHub Release.

## Prerequisites

Before releasing, verify:

1. **All tests pass:**
```bash
cargo test
cargo clippy -- -D warnings
cargo fmt --check
```

2. **Main branch is clean and up to date:**
```bash
git checkout main && git pull
git status  # must be clean
git log --oneline -5  # review recent commits
```

3. **CI is green** on the latest commit:
```bash
gh run list --limit 1
```

## Making a release

### Step 1: Create release branch

```bash
git checkout -b release/v<version> main
```

### Step 2: Bump version and changelog

Use `cog bump` with `--skip-push` (since we can't push directly to main):

```bash
cog bump --<level> --skip-push    # or --auto --skip-push
```

This will:
1. Bump the version in `Cargo.toml`
2. Generate/update `CHANGELOG.md` from conventional commits
3. Create a bump commit
4. Create a git tag `v<new_version>`

If `cog bump` doesn't support `--skip-push`, do it manually:
1. Edit `Cargo.toml` version field
2. Run `cog changelog > CHANGELOG.md` (or update manually)
3. Commit: `git commit -am "chore(release): v<version>"`

### Step 3: Push branch and create PR

```bash
git push -u origin release/v<version>
gh pr create --title "chore(release): v<version>" --body "Version bump and changelog for v<version>"
```

Wait for CI to pass, then merge the PR.

### Step 4: Tag and push

After the PR is merged, tag main and push the tag:

```bash
git checkout main && git pull
git tag v<version>
git push origin v<version>
```

The tag push triggers `.github/workflows/release.yml`, which builds binaries for macOS, Linux, and Windows, and creates a GitHub Release.

### Release levels

| Level | Example | Use case |
|-------|---------|----------|
| `--patch` | 0.1.0 → 0.1.1 | Bug fixes |
| `--minor` | 0.1.0 → 0.2.0 | New features |
| `--major` | 0.1.0 → 1.0.0 | Breaking changes |
| `--minor --pre rc` | 0.1.0 → 0.2.0-rc.1 | Release candidate |
| `--auto` | (auto-detected) | Let commits decide |

### Step 5: Monitor the release build

```bash
gh run list --limit 1                  # find the run ID
gh run watch <run-id> --exit-status    # live follow
```

If a build fails:
```bash
gh run view --job=<job-id> --log-failed
```

After success, verify the GitHub Release:
```bash
gh release view v<version>
```

## Configuration

- **`cog.toml`** — cocogitto config (tag prefix, bump hooks, changelog, commit validation)
- **`Cargo.toml`** — version field, `[package.metadata.dist]`
- **`.github/workflows/release.yml`** — auto-generated by `dist generate`, do not hand-edit

## Important notes

- `publish = false` — no crates.io publishing. Releases are GitHub-only for now.
- Tag format is `v{version}` (e.g., `v0.1.0`), configured by `tag_prefix = "v"` in `cog.toml`.
- Prerelease tags (e.g., `v0.1.0-rc.1`) create a GitHub Release marked as prerelease.
- `--auto` reads commits since last tag: `feat:` → minor, `fix:` → patch, `BREAKING CHANGE` → major.
- If cargo-dist config changes, regenerate the workflow: `dist generate`
- Branch protection blocks direct pushes to main — releases always go through a PR. Tags are not blocked.