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.
Go code review guidelines for the Cog codebase
Python code review guidelines for the Cog SDK
Rust code review guidelines for Coglet
Cog architecture and cross-cutting review guidelines
| name | release-cog |
| description | Guide and automate the Cog release process |
This skill helps you release new versions of Cog. Cog is a multi-language, multi-artifact project with a carefully orchestrated release process.
Cog releases include:
| 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 | ✗ | ✗ | ✗ |
# 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
git checkout -b release/v0.18.0
git push origin release/v0.18.0
# 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"
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
# Watch the release build workflow
gh workflow view release-build.yaml
# Or watch in real-time
gh run watch
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.
Style guidelines:
cog run command. ...")(#3015)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
)"
release-publish.yaml which publishes to PyPI and crates.iorelease-build.yaml - Triggered on version tags
release-publish.yaml - Triggered when release is published
homebrew-tap.yaml - Updates Homebrew cask
.github/cog.rb.tmplreplicate/homebrew-tap| File | Purpose |
|---|---|
VERSION.txt | Canonical version (single source of truth) |
crates/Cargo.toml | Rust workspace version |
crates/Cargo.lock | Locked dependency versions |
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.
Before creating a release tag:
mise run testmise run lintVERSION.txtmise run version:check passescrates/Cargo.toml matches VERSION.txtmise run docs:llm)Version mismatch! VERSION.txt has X but tag is vY
Fix: Run mise run version:bump Y, push, then re-tag.
Release tags must be on the main branch
Fix: Merge your changes to main, then tag from main.
gh release delete v0.18.0 --yesgit push --delete origin v0.18.0 && git tag -d v0.18.0If 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
pypi, crates-io, and homebrew environments in GitHub repo settingsdist/ at Docker build time, not embedded in binary