Skip to main content

release

Prepare a Python package for PyPI release by updating the version, building, and verifying the distribution.

Dual-purpose Tutorials
This how-to was written to be readable by both humans and machines. This box marks the spot where user-provided context would normally be inserted for the machine.

Process​

Step 0: Gather information​

Gather the following information from the user-provided context:

  • Target version (e.g., 0.1.0a1 for first alpha, 0.1.0 for stable)

If unclear, ask the user for the target version.

Step 1: Update version and commit​

Update pyproject.toml to set the target version in the [tool.poetry] section, then use the committer agent to commit the change.

Step 2: Build and verify​

Clean previous builds, build fresh distributions, and verify:

rm -rf dist/ && poetry build

Then run verification checks:

ls -lh dist/
tar -tzf dist/*.tar.gz | grep "bundled/scripts/nl.*\.md" | wc -l
tar -tzf dist/*.tar.gz | grep -E "docs/|tests/" && echo "Found excluded files (unexpected)" || echo "No excluded files (correct)"

Step 3: Provide publishing instructions​

Tell the user the package is ready and provide these instructions:

To test on TestPyPI first (recommended):

poetry publish -r testpypi

Then install and test:

python -m venv /tmp/test-mekara
source /tmp/test-mekara/bin/activate
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ mekara==<version>
mekara --version
deactivate
rm -rf /tmp/test-mekara

To publish to real PyPI

poetry publish

Key Principles​

  • Verify before publishing: Always build and verify the package contents before handing off to the user for publishing
  • Test on TestPyPI first: TestPyPI exists specifically for testing the full publish/install flow without affecting the real PyPI index
  • User publishes manually: The user should always manually run the publish command after reviewing the prepared package—never auto-publish