release

Release fromargs

This is a repository-local skill for skillz-that-grillz. It lives under .agents/skills/release/, with a .claude/skills/ symlink for Claude Code. metadata.internal: true hides it from npx skills add. Do not move it into the published skills/ tree.

A tag push publishes to PyPI after one approval, and PyPI never accepts the same version twice. Treat the tag push and the approval as irreversible.

Release contract

• packages/fromargs/CHANGELOG.md is the only source of release notes. just fromargs-release-notes <version> prints one section and fails when it is missing or empty.
• .github/workflows/publish-fromargs.yml runs on a fromargs-v* tag. Its build job requires the tag commit on main and the tag version equal to packages/fromargs/pyproject.toml.
• The publish job waits for the pypi environment approval, then uploads with trusted publishing.
• The github-release job creates the GitHub release with --latest=false. It fails when the tag moved after the build.
• The wedge bundles and the cheese-cave example lock embed the fromargs source, so a version change needs a rebuild.

1. Preflight

1. Switch to main, pull with --ff-only, and require a clean tree.
2. Read the ## [Unreleased] section of packages/fromargs/CHANGELOG.md. Stop when it is empty.
3. Choose the version. Use the argument when the user gives one. Otherwise, propose the next minor version for a 0.x release with a Breaking entry, and the next patch version for other changes. Confirm the proposed version with the user.
4. Stop when the tag fromargs-v<version> exists on origin or https://pypi.org/pypi/fromargs/<version>/json returns 200.

2. Prepare the release PR

1. Create the branch chore/fromargs-release-<version>.

2. In packages/fromargs/CHANGELOG.md, move the Unreleased entries under ## [<version>] - <YYYY-MM-DD> with today's date. Keep an empty ## [Unreleased] heading.

3. Update the link references at the end of the CHANGELOG. [Unreleased] compares fromargs-v<version>...HEAD. Add [<version>] to compare the previous tag with fromargs-v<version>.

4. Set version = "<version>" in packages/fromargs/pyproject.toml.

5. When the minor version changes, set the fromargs range in pyproject.toml and packages/wedge/pyproject.toml to >=<major>.<minor>.0,<<major>.<next minor>.

6. Relock the workspace with the uv version that the workflow pins in its setup-uv step, so the lockfile revision stays compatible with CI:

   uvx uv@<ci-uv-version> lock
   

7. Rebuild the artifacts that embed fromargs:

   uv run --locked --project packages/wedge wedge lock --root packages/wedge/examples/skills
   uv run --locked --project packages/wedge wedge bundle skills/skillz
   

8. Run just fromargs-release-notes <version> and read the output. It must show the complete new section.

9. Run uv build --package fromargs --no-sources --out-dir <temp dir> and uvx twine check <temp dir>/*.

10. Run just build. Stop on a new failure. Compare any failure with a clean main checkout before you call it a baseline failure.

11. Commit the named files as chore(fromargs): release <version>. Push the branch and open a PR against main. Put the release notes and the post-merge steps in the PR body.

3. Merge

1. Wait for every PR check to pass. Resolve or answer every review thread.
2. Get explicit user approval to merge, unless the user asked for the complete release in this session.
3. Squash-merge with gh pr merge <n> --squash --match-head-commit <sha>. Record the merge commit SHA.
4. When the merge date differs from the CHANGELOG date, fix the date in a new PR before you tag.

4. Tag and approve

1. Fetch main. Confirm that the merge commit is on origin/main and that it has the new version and CHANGELOG section.

2. Create and push an annotated tag on the merge commit:

   git tag -a fromargs-v<version> <merge-sha> -m "Release fromargs <version>"
   git push origin fromargs-v<version>
   

3. Find the publish fromargs run for the tag. Wait until the build job passes and the run waits on the pypi environment.

4. Approve the deployment only after the user approves it, unless the user asked for the complete release in this session:

   gh api repos/<owner>/<repo>/actions/runs/<run-id>/pending_deployments \
     -X POST -F "environment_ids[]=<pypi-env-id>" -f state=approved \
     -f comment="Approve fromargs <version>"
   

5. Verify

1. Watch the run to completion. Every job must succeed.
2. Read https://pypi.org/pypi/fromargs/<version>/json. Confirm the version, the dependency ranges, and one wheel and one sdist.
3. Read gh release view fromargs-v<version>. Confirm that it is not a draft, that its body starts with the CHANGELOG section, and that both dist files are attached.
4. Confirm that the repository's latest release did not change.

Failure rules

• Never move, delete, or re-push a published tag. A new fix needs a new patch version.
• When the build job fails, no upload happened. Fix the cause on main, delete the unpublished tag only with user approval, and tag again.
• When PyPI has the version but the github-release job failed, re-run only the failed job with gh run rerun <run-id> --failed.
• Never approve a deployment for a run whose tag does not point at the reviewed merge commit.

Report

Report the PR, the merge commit, the tag, the workflow run, the PyPI URL, and the GitHub release URL. Name every check that did not run.