65 lines
2.1 KiB
Markdown
65 lines
2.1 KiB
Markdown
# 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
|
|
|
|
1. Create or sign in to an account at <https://pypi.org/>.
|
|
2. Verify the account email address.
|
|
3. Enable two-factor authentication and store the recovery codes in the
|
|
password manager and an offline recovery location.
|
|
4. For the first upload only, create an account-scoped API token. PyPI cannot
|
|
create a project-scoped token until the project exists.
|
|
5. 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|