agentleFS
AetherCore-DevAetherCore-Dev/ag402/.claude/skills/releasing-to-pypi/SKILL.md

releasing-to-pypi

Skill9 starsChanged 8 months agoMITView on GitHub

Use when committing code changes that will be tagged and released to PyPI, before creating any git commits, to ensure lint, version bump, tag placement, and changelog are all correct in one shot

  • Deletes or force-pushes
  • Commits and pushes

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 8 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    If lint fails, fix it. Never commit code that fails lint — fixing lint after commit requires either amend (breaks protected branches) or an …

    line 30
  2. Distinctive:

    All tests must pass. Do not commit with known failures.

    line 46
  3. Distinctive:

    Update all 10 files in a single commit:

    line 56
  4. Distinctive:

    All lines must show the same version.

    line 81
  5. Distinctive:

    Check and update test counts / feature descriptions in:

    line 87
  6. Distinctive:

    CRITICAL: Never commit internal planning docs or secrets.

    line 97
  7. Distinctive:

    After creating the release, verify the workflow triggered:

    line 144
  8. Distinctive:

    When pushing to GitHub, use the authenticated HTTPS URL:

    line 217

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Releasing to PyPI

Overview

A release to PyPI in this project requires all steps completed atomically before pushing. The publish workflow triggers on GitHub Release creation and checks out the tag's commit — if that commit has wrong versions, stale lint, or missing changelog, the release fails and cannot be re-uploaded to PyPI (immutable filenames).

Core principle: The tag must point to a commit where every file is release-ready. Work backwards from that constraint.

When to Use

  • Committing code that will be tagged for release
  • Bumping versions for a new PyPI publish
  • Creating any git tag prefixed with v

The Checklist

MANDATORY: Execute every step in order. Do not skip. Do not reorder.

Step 1: Lint BEFORE Committing

ruff check protocol/ core/ adapters/

If lint fails, fix it. Never commit code that fails lint — fixing lint after commit requires either amend (breaks protected branches) or an extra commit (splits changes, tag placement becomes error-prone).

Step 2: Run ALL Tests BEFORE Committing

# Protocol tests
pytest protocol/tests/ --timeout=30

# Core tests (excluding on-chain)
pytest core/tests/ --timeout=30 -m "not devnet and not localnet and not mainnet"

# Adapter tests
cd adapters/mcp && pytest tests/ --timeout=30 && cd ../..
cd adapters/client_mcp && pytest tests/ --timeout=30 && cd ../..

All tests must pass. Do not commit with known failures.

Step 3: Version Bump — ALL 10 Files in ONE Commit

Determine the next version. Check existing tags:

git tag -l 'v*' --sort=-v:refname | head -5

Update all 10 files in a single commit:

#FileFieldNotes
1protocol/pyproject.tomlversion = "X.Y.Z"
2protocol/open402/__init__.py__version__ = "X.Y.Z"⚠️ Easy to forget
3core/pyproject.tomlversion = "X.Y.Z"
4core/ag402_core/__init__.py__version__ = "X.Y.Z"⚠️ Easy to forget
5adapters/mcp/pyproject.tomlversion = "X.Y.Z"
6adapters/mcp/ag402_mcp/__init__.py__version__ = "X.Y.Z"⚠️ Easy to forget
7adapters/client_mcp/pyproject.tomlversion = "X.Y.Z"
8adapters/client_mcp/ag402_client_mcp/__init__.py__version__ = "X.Y.Z"⚠️ Easy to forget
9adapters/client_mcp/tests/test_server.pyassert __version__ == "X.Y.Z"⚠️ Test will fail in CI if missed
10CHANGELOG.mdAdd ## [X.Y.Z] section at top

Verification command — run this after editing to catch misses:

grep -r '"0\.1\.' protocol/pyproject.toml protocol/open402/__init__.py \
  core/pyproject.toml core/ag402_core/__init__.py \
  adapters/mcp/pyproject.toml adapters/mcp/ag402_mcp/__init__.py \
  adapters/client_mcp/pyproject.toml adapters/client_mcp/ag402_client_mcp/__init__.py \
  adapters/client_mcp/tests/test_server.py

All lines must show the same version. If any differ → STOP and fix.

Never split version bump and code changes into separate commits before tagging. The tag must land on a commit that has both the code changes AND the correct version numbers.

Step 4: Update Documentation

Check and update test counts / feature descriptions in:

FileWhat to check
README.mdTest count badge, config env var table, feature descriptions
SECURITY.mdTest totals, security feature list
CHANGELOG.mdNew version section with correct date and changes

Step 5: Check for Sensitive / Internal Files

CRITICAL: Never commit internal planning docs or secrets.

# Verify .gitignore excludes internal docs
grep '开源发布行动计划' .gitignore  # Must be present

# Verify no secrets in staged files
git diff --cached --name-only | xargs grep -l 'PRIVATE_KEY\|ghp_\|sk-' 2>/dev/null
# Must return empty

Step 6: Tag the FINAL Commit

git tag -a vX.Y.Z -m "vX.Y.Z: short description"

The tag MUST point to the commit containing the version bump. Verify:

git log --oneline -1 vX.Y.Z
# Must show the version bump commit, NOT an earlier commit

Step 7: Push Commit + Tag Together

git push -u origin main && git push origin vX.Y.Z

Step 8: Create GitHub Release (TRIGGERS PyPI Publish)

This is the step that actually publishes to PyPI. The publish.yml workflow triggers on release: types: [published], NOT on tag push. Pushing a tag alone does NOT publish to PyPI.

gh release create vX.Y.Z --title "vX.Y.Z — Short description" --notes "$(cat <<'EOF'
## What's Changed

- Feature 1
- Feature 2
- ...

**Full Changelog**: https://github.com/AetherCore-Dev/ag402/blob/main/CHANGELOG.md
EOF
)"

After creating the release, verify the workflow triggered:

gh run list --workflow=publish.yml --limit=1

Mistakes This Skill Prevents

MistakeConsequencePrevention
Commit code, then fix lint separatelyExtra commit; tag placed on wrong commitStep 1: lint before commit
Forget __init__.py versions__version__ mismatches pyproject.toml; import shows wrong version; test fails in CIStep 3: all 10 files + verification command
Forget test assertion versiontest_server.py::test_package_version fails in CI → release blockedStep 3: file #9 in the checklist
Tag on code commit, version bump in later commitCI checks out tag → builds old version → PyPI rejects duplicate filenameStep 3+6: version bump + tag on same commit
Push tag but skip gh release createPyPI publish never triggers — publish.yml fires on release: [published], not on tag pushStep 8: always create GitHub Release
Commit internal docs (开源发布行动计划.md)Internal planning docs leak to public repoStep 5: verify .gitignore + check staged files
Forget CHANGELOG.mdRelease notes incompleteStep 3: CHANGELOG in same commit
Forget to update README/SECURITY.mdStale test counts, missing env varsStep 4: documentation checklist
git push --force on protected branchPush rejected; requires extra fixup commitsNever amend pushed commits; get it right first time
Tag points to wrong commitCI builds wrong version; PyPI upload fails with "File already exists"Step 6: verify tag target

Red Flags — STOP and Recheck

  • About to git commit but haven't run ruff check → STOP
  • About to git tag but version bump is in a different commit → STOP
  • grep verification shows mixed version numbers → STOP
  • About to git push --force on main → STOP (protected branch)
  • About to gh release create but git log --oneline -1 vX.Y.Z doesn't show version bump → STOP
  • About to git commit --amend on an already-pushed commit → STOP
  • git diff --cached shows 开源发布行动计划.md or other internal files → STOP
  • Pushed tag but didn't run gh release create → STOP (PyPI won't publish)

Quick Reference: Ideal Single-Shot Flow

# 1. Lint
ruff check protocol/ core/ adapters/

# 2. Test (all 4 packages)
pytest protocol/tests/ --timeout=30
pytest core/tests/ --timeout=30 -m "not devnet and not localnet and not mainnet"
(cd adapters/mcp && pytest tests/ --timeout=30)
(cd adapters/client_mcp && pytest tests/ --timeout=30)

# 3. Bump versions (all 10 files) + update docs + update CHANGELOG
#    Then verify:
grep -r '"X\.Y\.Z"' protocol/pyproject.toml protocol/open402/__init__.py \
  core/pyproject.toml core/ag402_core/__init__.py \
  adapters/mcp/pyproject.toml adapters/mcp/ag402_mcp/__init__.py \
  adapters/client_mcp/pyproject.toml adapters/client_mcp/ag402_client_mcp/__init__.py \
  adapters/client_mcp/tests/test_server.py

# 4. Check no internal files staged
git diff --cached --name-only  # Should NOT include 开源发布行动计划.md

# 5. Commit
git add <specific files> && git commit -m "chore: release vX.Y.Z — description"

# 6. Tag the version-bumped commit
git tag -a vX.Y.Z -m "vX.Y.Z: description"

# 7. Push together
git push -u origin main && git push origin vX.Y.Z

# 8. Create GitHub Release (THIS triggers PyPI publish)
gh release create vX.Y.Z --title "vX.Y.Z — Description" --notes "..."

# 9. Verify publish workflow triggered
gh run list --workflow=publish.yml --limit=1

Git Remote Configuration

When pushing to GitHub, use the authenticated HTTPS URL:

git remote set-url origin https://<PAT>@github.com/AetherCore-Dev/ag402.git
git config user.name "AetherCoreDev"
git config user.email "aethercore.dev@proton.me"

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.