Publishing to GitHub and PyPI

This page is for maintainers who publish Cisformer releases.

Prerequisites

  • Work from a clean git checkout with permission to push to GitHub.

  • Install packaging tools in the active Python environment:

python -m pip install build twine

  • Configure a PyPI token. The simplest non-interactive setup is:

export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-your-token-here

  • Update release notes before publishing if the release has user-visible changes.

Dry Run

The script is safe by default. Without --yes, it only prints the actions it would run:

scripts/publish.sh 1.1.1

Publish

Run this from the project root:

scripts/publish.sh 1.1.1 --yes

The script will:

  1. Update pyproject.toml and docs/source/conf.py to the requested version.

  2. Build the source distribution and wheel.

  3. Run twine check on the generated files.

  4. Commit the version bump if needed.

  5. Create and push the v<version> git tag to GitHub.

  6. Upload the built package files to PyPI.

By default, package files are built in a temporary directory so old files under dist/ are not uploaded by accident. To keep the generated package files in the project directory, set DIST_DIR:

DIST_DIR=dist scripts/publish.sh 1.1.1 --yes

PyPI does not allow reusing a published version number. If upload fails because the version already exists, bump the version and rerun the release.

TestPyPI

To test the package upload without touching the main PyPI project:

scripts/publish.sh 1.1.1 --yes --repository-url https://test.pypi.org/legacy/

Use a TestPyPI token in TWINE_PASSWORD for this command.

Useful Options

  • --remote upstream: push to another git remote instead of origin.

  • --branch main: push a specific branch instead of the current branch.

  • --skip-git: build and upload to PyPI without committing, tagging, or pushing.

  • --skip-pypi: update GitHub only, without building or uploading the package.