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

Quick Release Commands

1. Bump Version (if needed)

# 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

git checkout -b release/v0.18.0
git push origin release/v0.18.0

3. Create PR to main

# 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

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

# 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:

gh release view v0.19.0 --json body

To gather commits since the last release:

# 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:

### 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:

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

Version Constraints

The SDK (pyproject.toml) has a dependency on coglet:

coglet>=0.1.0,<1.0

During release build, this is updated to:

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:

# 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