token-throttle CLAUDE.md

token-throttle

Releasing a New Version

Releases are fully automated via GitHub Actions. Do NOT bump versions or publish locally.

Trigger a release

gh workflow run release.yml --ref main -f bump=patch   # 0.5.0 -> 0.5.1
gh workflow run release.yml --ref main -f bump=minor   # 0.5.0 -> 0.6.0
gh workflow run release.yml --ref main -f bump=major   # 0.6.0 -> 1.0.0

What the workflow does

1. Verifies manual dispatch is running from refs/heads/main with a non-empty bump input, then runs full CI test suite (.github/workflows/ci.yml)
2. bump-my-version bump <patch|minor|major> — updates version in pyproject.toml and token_throttle/__init__.py, creates a commit
3. devtools/bump_readme_version.py — updates pip install version bounds in README.md
4. uv lock — syncs uv.lock with the new version
5. ruff check --fix, ruff format, then ruff check — applies safe lint autofixes, formats, and fails if issues remain
6. Creates a second commit with lockfile/formatting changes (if any)
7. Porcelain check — fails the release if the working tree is still dirty after all fixes
8. Creates an annotated vX.Y.Z tag and atomically pushes main plus the tag
9. Internally re-dispatches release.yml on the immutable tag
10. Re-runs full CI test suite on the tag
11. Runs uv build before tagging, then builds again from the tag and publishes to PyPI via OIDC trusted publishing

Version is tracked in two places

• pyproject.toml (version field + [tool.bumpversion] current_version)
• token_throttle/__init__.py (__version__)

Both are updated automatically by bump-my-version. Do not edit these manually.

Development

uv sync --group dev
uv run pytest tests/unit
uv run ruff check .

tests/unit doesn't require Redis — but its default --redis-url is redis://localhost:6379, so tests that talk to a real Redis will use one if it's reachable there, and some of those flush the database around every test. The suite refuses to run (aborts the whole session) against a non-empty database unless you opt in. Point at a dedicated, empty DB index instead of a shared one: