Use this skill when updating, reviewing, or creating architecture documentation in the architecture/ directory. This includes after refactors, feature additions, component changes, or when auditing docs for accuracy. Use it any time code changes affect how Cog's internals work -- new packages, changed IPC protocols, modified build pipeline, runtime behavior changes. Also use it proactively when reviewing PRs that touch core systems to check whether the architecture docs need updating.

2026-05-089.4k

go-review

replicate/cog

Go code review guidelines for the Cog codebase

2026-04-249.4k

python-review

replicate/cog

Python code review guidelines for the Cog SDK

2026-04-249.4k

rust-review

replicate/cog

Rust code review guidelines for Coglet

2026-04-249.4k

cog-review

replicate/cog

Cog architecture and cross-cutting review guidelines

2026-03-319.4k

name	release-cog
description	Guide and automate the Cog release process

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)

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

New features — New commands, new APIs, new annotations, new capabilities.
Improvements — Performance, reliability, DX improvements, removals of legacy paths, build improvements.
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

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

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

Delete the GitHub release if it was created: gh release delete v0.18.0 --yes
Delete the tag: git push --delete origin v0.18.0 && git tag -d v0.18.0
Fix the issue
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