Release Guide

Publishing to PyPI

1. Update the version

   Edit pyproject.toml and bump the version number:

   [project]
   name = "mcilspy"
   version = "0.6.0"

   mcilspy uses date-aware versioning. Patch versions within a date are fine for same-day fixes.

2. Clean and build

   Always clean dist/ before building. Stale files from previous builds cause duplicate upload attempts — PyPI rejects already-published versions.

   rm -rf dist/ && uv build

   This produces both a .tar.gz source distribution and a .whl wheel in dist/.

3. Check the package

   Verify the package metadata and structure before uploading:

   twine check dist/*

4. Upload to PyPI

   uv publish --token $(grep password ~/.pypirc | head -1 | awk '{print $3}')

5. Verify the release

   pip index versions mcilspy

   Or install it fresh:

   pip install mcilspy==0.6.0

Important Notes

Caution

PyPI is immutable per version. You cannot re-upload or fix metadata for a published version. If you need to fix something after publishing, bump to a new version. For same-day fixes, use incremental patch versions (e.g., 0.5.1, 0.5.2).

Caution

uv publish does not read ~/.pypirc by default. You must pass the API token explicitly via --token. The command above extracts it from your existing .pypirc file.

Pre-Release Checklist

Before publishing, verify:

• All tests pass: pytest
• Linting is clean: ruff check src/
• Version in pyproject.toml is updated
• Changelog is updated in the docs site
• The package installs and runs locally: uv pip install -e . && mcilspy

Build System

mcilspy uses Hatch as its build backend:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/mcilspy"]

The src layout means the package source lives in src/mcilspy/ and the wheel maps it to mcilspy/ at install time. The entry point is defined as:

[project.scripts]
mcilspy = "mcilspy.server:main"

This creates the mcilspy CLI command that users invoke directly or through uvx mcilspy.