2.1 KiB
Publishing CmdForge to PyPI
PyPI releases are public and immutable. A release version must never be reused for different bytes, even if an upload contains a mistake.
One-time account setup
- Create or sign in to an account at https://pypi.org/.
- Verify the account email address.
- Enable two-factor authentication and store the recovery codes in the password manager and an offline recovery location.
- For the first upload only, create an account-scoped API token. PyPI cannot create a project-scoped token until the project exists.
- Do not put a PyPI token in Git,
.pypirc, chat, command arguments, or shell history. Let Twine prompt for it interactively.
After the first successful upload, immediately revoke the account-scoped token
and create a new token restricted to the cmdforge project.
Prepare and validate a release
Update the version in both pyproject.toml and src/cmdforge/__init__.py, then
add the release to CHANGELOG.md. From a clean checkout:
python -m pip install -e '.[release]'
pytest tests/ -m "not integration"
python -m build
python -m twine check dist/*
Inspect the wheel and source archive, then install the wheel into a clean temporary virtual environment and exercise both entry points. Do not upload an artifact that was built before the release commit.
Upload
Run Twine interactively so the token is not recorded in shell history:
python -m twine upload dist/*
When prompted, use __token__ as the username and paste the API token as the
password. Once uploaded, verify the public project and install from PyPI in a
new environment:
python -m venv /tmp/cmdforge-pypi-check
/tmp/cmdforge-pypi-check/bin/pip install 'cmdforge[mcp,pty]'
/tmp/cmdforge-pypi-check/bin/cmdforge --version
/tmp/cmdforge-pypi-check/bin/cmdforge --help
Tag and push only the commit whose artifacts were published:
git tag -a v0.2.0 -m "CmdForge 0.2.0"
git push origin main
git push origin v0.2.0
If an upload is wrong, fix it, increment the version, rebuild, and publish a new release. Never delete and reuse the version number.