prepare-release

name	prepare-release
description	Prepares a torchjd package release by verifying the changelog, README, bumping the version in pyproject.toml, and opening a release PR. Use when a maintainer asks to prepare a release or to release.

Prepare TorchJD Release

This skill covers the pre-merge steps of the release process.

For agents: invoke as /prepare-release X.Y.Z (e.g. /prepare-release 0.16.0). If no version is provided, read the current version from pyproject.toml and ask the user what the new version should be before proceeding.

For humans: follow the numbered steps below in your terminal. Replace X.Y.Z with the version you are releasing and yyyy-mm-dd with today's date.

---

Instructions

Step 1: Determine the version

Read pyproject.toml to find the current version field under [project]. The new release version is either provided as an argument or must be confirmed with the user before continuing.

Verify it follows Semantic Versioning.

Step 2: Verify CHANGELOG

Read CHANGELOG.md and compare it against the commits done since the last version release. Verify that no user-facing change was forgotten, and that all were correctly added under the [Unreleased] section.

Step 3: Check README for interface changes

Read CHANGELOG.md and identify any entries in the [Unreleased] section that affect the public interface (new or removed classes, functions, or arguments; changed signatures or behavior).

If such entries exist, read README.md and verify it accurately describes the current interface.

If a table listing methods exists in README.md, add to it any newly added method of the corresponding type.

If anything else seems missing, report that to the user.

Step 4: Run the unit tests

CRITICAL: Do not skip this step, even partially.

Run the unit tests and confirm they all pass both on CPU and GPU (you need a CUDA-enabled GPU for this):

uv run pytest tests/unit
PYTEST_TORCH_DEVICE=cuda:0 uv run pytest tests/unit

If any tests fail, stop and report the failures. Do not proceed to the next steps.

Step 5: Add the version header to the changelog

In CHANGELOG.md, insert a new ## [X.Y.Z] - yyyy-mm-dd heading immediately after the blank line that follows ## [Unreleased], before the existing subsections:

 ## [Unreleased]

+## [X.Y.Z] - yyyy-mm-dd
+
 ### Added

The [Unreleased] section stays in place and will accumulate entries for the next release. The newly-inserted heading claims the existing content as its own.

Step 6: Bump the version in pyproject.toml

In pyproject.toml, update the version field under [project]:

-version = "A.B.C"
+version = "X.Y.Z"

Step 7: Open the release PR

Checkout a new branch release-vX.Y.Z, stage changes, commit, then open a pull request targeting main. Return the PR URL when done.

Step 8: Create a draft release on GitHub

CRITICAL: The release you'll create should ALWAYS be a draft. Never even suggest to make the real release. A maintainer will manually release the draft if it seems ready.

The command should be:

gh release create vX.Y.Z --draft --title vX.Y.Z --notes "<insert notes here>"

To write the actual release notes, look at what is done in recent releases and suggest the new notes. Make it short. Also, prompt the user for a good-looking emoji (propose a list) to use in the main section of the release notes.

---