release-cog

# Cog Release Skill This skill helps you release new versions of Cog. Cog is a multi-language, multi-artifact project with a carefully orchestrated release process. ## Overview Cog releases include: - **CLI binaries** (Go) - macOS and Linux, x86_64 and ARM64 - **coglet Python wheels** (Rust/PyO3) - Linux x86_64/ARM64, macOS ARM64 - **cog SDK Python wheel** (Python) - Universal - **coglet Rust crate** - Published to crates.io ## Release Types | Type | Format | Example | Branch | PyPI | crates.io | Homebrew | | --------------- | ------------------------------- | ------------ | ------ | ---- | --------- | -------- | | **Stable** | `v0.17.0` | v0.18.0 | main | ✓ | ✓ | ✓ | | **Pre-release** | `v0.17.0-alpha3`, `v0.17.0-rc1` | v0.18.0-rc1 | main | ✓ | ✓ | ✗ | | **Dev** | `v0.17.0-dev1` | v0.18.0-dev2 | any | ✗ | ✗ | ✗ | ## Quick Release Commands ### 1. Bump Version (if needed) ```bash # Check current version mise run version # Bump to new version (updates VERSION.txt, Cargo.toml, Cargo.lock, commits) mise run version:bump 0.18.0 ``` ### 2. Create a release branch and push ```bash git checkout -b release/v0.18.0 git push origin release/v0.18.0 ``` ### 3. Create PR to main ```bash # Open a pull request to main, get it reviewed and merged. Then you can create the release tag from main. gh pr create --base main --head release/v0.18.0 --title "Release v0.18.0" --body "Release description and notes" ``` ### 4. Create and Push Tag ```bash git checkout main && git pull origin main # For stable release git tag v0.18.0 git push origin v0.18.0 # For pre-release git tag v0.18.0-rc1 git push origin v0.18.0-rc1 # For dev release (can be from any branch) git tag v0.18.0-dev1 git push origin v0.18.0-dev1 ``` ### 5. Monitor Release Build ```bash # Watch the release build workflow gh workflow view release-build.yaml # Or watch in real-time gh run watch ``` ### 6. Write Release Notes After the draft release is created, update the release notes to follow the project's standard format. The release notes are not auto-generated from commit messages — they must be hand-written and categorized. **To see the previous release's format:** ```bash gh release view v0.19.0 --json body ``` **To gather commits since the last release:** ```bash # List commits between the previous release and this one git log --oneline v0.19.0..v0.20.0 --no-merges ``` **Release notes structure:** Group changes into three sections. Only include sections that have items. 1. **New features** — New commands, new APIs, new annotations, new capabilities. 2. **Improvements** — Performance, reliability, DX improvements, removals of legacy paths, build improvements. 3. **Bug fixes** — User-visible bug fixes. Prefer "Now does X correctly" over "Fixed X". **Style guidelines:** - Lead each bullet with a **bold, user-facing summary sentence** (e.g., "**`cog run` command.** ...") - Follow with a short explanation of what changed and why it matters - Reference the PR number in parentheses at the end: `(#3015)` - Use backticks for commands, flags, and code references - Omit internal refactors, dependency bumps, and CI-only changes unless they are user-facing - Omit version bump commits **Example:** ```markdown ### New features - **`cog run` command.** The `cog predict` command has been renamed to `cog run` with full backward compatibility. `cog predict` still works as an alias. (#3015) - **Model refs for `cog push` and weights commands.** You can now reference models by name (e.g., `r8.im/user/model`) instead of full image URLs when pushing or managing weights. (#3018) ### Improvements - **Runtime schema generation fully removed.** The legacy runtime Python schema generation path has been completely removed. Cog exclusively uses static schema generation, making builds faster and more reliable. (#3003) ### Bug fixes - **Pushing a model with a version tag now emits a clean URL.** The Replicate model URL printed after `cog push` no longer includes the image tag (e.g., `:latest`), preventing 404 errors when users click the link. (#3020) ``` **To update the draft release:** ```bash gh release edit v0.20.0 --notes "$(cat <<'EOF' ### New features - ... ### Improvements - ... ### Bug fixes - ... EOF )" ``` ### 7. Publish Release (stable/pre-release only) - Go to GitHub Releases page - Find the draft release - Review release notes - Click "Publish release" - This triggers `release-publish.yaml` which publishes to PyPI and crates.io ## Release Process Details ### Automated Workflows 1. **`release-build.yaml`** - Triggered on version tags - Verifies tag matches VERSION.txt and Cargo.toml - Verifies stable/pre-release tags are on main branch - Builds SDK wheel (with updated coglet version constraint) - Builds coglet wheels for all platforms (Linux x64/ARM64, macOS ARM64) - Uses GoReleaser to build CLI binaries and create draft release - Uploads wheels to GitHub release - For dev releases: immediately publishes as pre-release 2. **`release-publish.yaml`** - Triggered when release is published - Publishes coglet wheels to PyPI - Publishes coglet crate to crates.io - Publishes cog SDK to PyPI (depends on coglet) - Updates Homebrew tap (stable releases only) 3. **`homebrew-tap.yaml`** - Updates Homebrew cask - Generates cask from `.github/cog.rb.tmpl` - Creates PR in `replicate/homebrew-tap` ### Version Files | File | Purpose | | ------------------- | ------------------------------------------ | | `VERSION.txt` | Canonical version (single source of truth) | | `crates/Cargo.toml` | Rust workspace version | | `crates/Cargo.lock` | Locked dependency versions | ### Version Constraints The SDK (`pyproject.toml`) has a dependency on coglet: ```toml coglet>=0.1.0,<1.0 ``` During release build, this is updated to: ```toml coglet>=0.18.0,<1.0 ``` This ensures the SDK depends on the matching coglet version. ## Pre-Release Checklist Before creating a release tag: - [ ] All tests pass: `mise run test` - [ ] Lint passes: `mise run lint` - [ ] Version is correct in `VERSION.txt` - [ ] `mise run version:check` passes - [ ] `crates/Cargo.toml` matches `VERSION.txt` - [ ] Changelog is updated (if applicable) - [ ] Documentation is updated (`mise run docs:llm`) ## Troubleshooting ### Version mismatch error ``` Version mismatch! VERSION.txt has X but tag is vY ``` Fix: Run `mise run version:bump Y`, push, then re-tag. ### Tag not on main ``` Release tags must be on the main branch ``` Fix: Merge your changes to main, then tag from main. ### Rebuilding a failed release 1. Delete the GitHub release if it was created: `gh release delete v0.18.0 --yes` 2. Delete the tag: `git push --delete origin v0.18.0 && git tag -d v0.18.0` 3. Fix the issue 4. Re-create and push the tag ### Manual PyPI publish (emergency) If the automated publish fails: ```bash # Download wheels from GitHub release gh release download v0.18.0 -p "coglet-*.whl" -D dist gh release download v0.18.0 -p "cog-*.whl" -D dist # Publish with twine twine upload dist/coglet-*.whl # First! twine upload dist/cog-*.whl # After coglet is uploaded ``` ## Architecture Notes - **Trusted Publishing**: PyPI and crates.io use OIDC trusted publishing (no API tokens in secrets) - **Environments Required**: Configure `pypi`, `crates-io`, and `homebrew` environments in GitHub repo settings - **CGO**: Required for go-tree-sitter (static Python schema parser) - **Zig**: Used for Linux cross-compilation (CC=zig cc) - **macOS builds**: Use native compiler (zig lacks macOS SDK stubs) - **Wheel discovery**: CLI discovers wheels from `dist/` at Docker build time, not embedded in binary