create-release

Create a CocoIndex Release

How a release works here

Publishing a GitHub release whose tag doesn't exist yet creates the v<version> tag on the release's target commit. That tag push starts .github/workflows/release.yml, which:

1. stamps the version from the tag into Cargo.toml, pyproject.toml and python/cocoindex/_version.py (.github/scripts/update_version.py). The checked-in versions stay placeholders (999.0.0, dynamic), so a release needs no version-bump commit;
2. builds the wheels (abi3 and free-threaded, every platform) and the sdist, and smoke-tests them;
3. uploads them to PyPI, then deploys the docs when the release is the repository's "Latest" one (the Docs Gate job).

So publishing the GitHub release is the one action that ships everything. Don't git tag and git push instead: that ships to PyPI with no release entry and no notes. And publishing can't be taken back — PyPI never accepts the same version twice — so the release is drafted first, shown to the user, and published only on their go-ahead.

A minor or major release is cut from main. A patch release is cut from the minor's release branch, release/<X.Y>, which starts at the minor's tag and takes only backports (dev/agent-skills/backport/SKILL.md says what qualifies and how one lands; AGENTS.md, Versioning, is the policy). The docs site shows the docs of the latest release, so a patch of an older minor is published with --latest=false (step 5) and deploys no docs.

Needs gh authenticated with push access to cocoindex-io/cocoindex. The commands below use placeholders: <branch> (main or release/1.1), <prev_tag> (e.g. v1.0.26), <sha> (full commit SHA), <version> (e.g. 1.1.0) and <tag> (v<version>).

1. Pin the branch, the commit and the previous release

git fetch origin --tags
git rev-parse origin/<branch>                              # <sha>
git describe --tags --abbrev=0 --match 'v[0-9]*' <sha>     # <prev_tag>: the newest release tag the commit descends from
git log --oneline <prev_tag>..<sha>