Menú
Create a new ATK release. Handles pre-flight checks, changelog generation, tagging, pushing, CI verification, and PyPI publication confirmation. Use when asked to cut a release, publish a new version, or ship changes.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
| name | release |
| description | Create a new ATK release. Handles pre-flight checks, changelog generation, tagging, pushing, CI verification, and PyPI publication confirmation. Use when asked to cut a release, publish a new version, or ship changes. |
| argument-hint | [version, e.g. 0.3.0] |
You are performing a release of the atk-cli package. This is a critical operation — follow every step in order. Do not skip steps. Do not assume success — verify it.
ATK uses hatch-vcs: the version is derived from git tags at build time, not hardcoded.
vX.Y.Z (e.g., v0.2.1)Z): bug fixes, small features, non-breaking changesY): new user-facing features, new commands, behavioral changesX): breaking changes to CLI interface, manifest schema, or plugin APIv1.0.0: minor bumps are for significant milestones; patches are the normPyPI receives the version without the v prefix (e.g., 0.2.1).
CRITICAL: PyPI does not allow re-uploads. If a version is published, it is permanent. Never force-move a tag that has been pushed. If a mistake is published, bump to the next patch.
If version was provided as argument, use v$ARGUMENTS. Otherwise:
git tag --sort=-v:refname | head -1 to find the current latest taggit log <latest-tag>..HEAD --oneline to see what changedRun ALL of these checks. If ANY fail, stop and report.
git status --short
EXPECT: Empty output (no uncommitted changes). If dirty, stop — all changes must be committed before release.
git branch --show-current
EXPECT: main. Releases are only cut from main.
git fetch origin main
git rev-list HEAD..origin/main --count
EXPECT: 0 (no commits on origin/main that we don't have). If behind, stop — pull first.
make check
EXPECT: Exit 0. This runs ruff (lint), mypy (types), and pytest (tests). All must be green.
gh run list --branch main --limit 3
EXPECT: The most recent CI run for HEAD is completed / success. If CI hasn't run for the current HEAD yet, wait or trigger it.
Check if there are any issues/PRs that should block this release:
gh issue list --state open --label "blocker" --limit 5
If blockers exist, report them and ask Sasha whether to proceed.
Generate a thorough changelog by analyzing what changed since the last release.
git tag --sort=-v:refname | head -1
git log <last-tag>..HEAD --oneline --no-merges
git diff <last-tag>..HEAD --stat
Read each commit and the diff. Organize into categories:
Write release notes in this format:
## What's New
### <Feature Name>
<2-3 sentence description with usage example>
### <Feature Name>
...
## Bug Fixes
- <one-liner per fix>
## Breaking Changes
- <one-liner with migration guidance>
## Upgrade
\```bash
pip install --upgrade atk-cli
# or
uv tool upgrade atk-cli
\```
<Any migration notes if needed>
Present the draft to Sasha for review before proceeding.
Before tagging, manually verify the key changes work. This is NOT optional.
For each new feature or significant change:
At minimum, always test:
atk --version outputs a valid versionatk status works without errors (if ATK Home exists)Only proceed here if all previous steps passed and Sasha approved the release notes.
git tag v<VERSION>
git push origin main
git push origin v<VERSION>
The tag push triggers the Publish to PyPI workflow automatically.
Both workflows must succeed before the release is complete.
gh run list --branch main --limit 3
Wait until the CI run for the current commit shows completed / success.
gh run list --workflow publish.yml --limit 3
Wait until the publish run shows completed / success.
If either workflow fails:
gh run view <run-id> --log | tail -50curl -s https://pypi.org/pypi/atk-cli/<VERSION>/json before deciding next steps.curl -s https://pypi.org/pypi/atk-cli/<VERSION>/json | python3 -c "import sys,json; d=json.load(sys.stdin); print('Version:', d['info']['version']); print('Summary:', d['info']['summary'])"
EXPECT: Version matches the release version. If this fails, the publish did not actually land on PyPI — investigate before creating the GitHub release.
gh release create v<VERSION> --title "v<VERSION> — <Short Title>" --notes "<release notes from Step 2>"
Use a HEREDOC for multi-line notes:
gh release create v<VERSION> --title "v<VERSION> — <Title>" --notes "$(cat <<'EOF'
<release notes here>
EOF
)"
gh release view v<VERSION>
uv pip install atk-cli==<VERSION> --dry-run
Summarize to Sasha:
https://pypi.org/project/atk-cli/<VERSION>/https://github.com/Svtoo/atk/releases/tag/v<VERSION>| Failure | Recovery |
|---|---|
| CI fails after tag push | Fix the issue, push fix to main, bump to next patch, re-tag |
| Publish fails but PyPI has the version | The version is burned — create GitHub release as-is |
| Publish fails and PyPI does NOT have it | Fix issue, delete the tag (git tag -d v<X> && git push origin :refs/tags/v<X>), re-tag same commit |
| Wrong content released | Cannot re-upload to PyPI. Bump patch, fix, release again |
| Tag pushed to wrong commit | If not yet on PyPI: delete remote tag, re-tag correct commit. If on PyPI: bump patch |