Prepare and publish a release

Release scope

Publish the reusable library, documentation, small examples and self-contained regression tests. Keep scientific campaigns, generated trajectories, local debug records and their private source trees in their own repositories. A tagged software release identifies algorithms and contracts; it is not a certificate of physical convergence or uncertainty coverage.

Local checks

Use the supported Windows/Python 3.12 environment:

uv sync --locked --group docs
uv run --no-sync python -m pytest tests
uv run --no-sync python tools/check_docs.py --execute
uv run --no-sync python docs/build.py
uv build --out-dir dist

The docs-check output defaults to a unique system temporary directory. Inspect the wheel and source archive, install the wheel into a separate clean environment and exercise public run, audit and continuation from an unrelated working directory. The source archive must also build independently. Contributor and CI dependencies are pinned in uv.lock; runtime requirements are declared in pyproject.toml.

Update pyproject.toml, hcphases.__version__, CITATION.cff, CHANGELOG.md and the version-bound documentation together. Preserve previous distributions and the implementation identities required by existing saved runs. Build after the final source edits; record artifact SHA256 hashes. Avoid claiming untested platforms.

First GitHub connection

Create an empty GitHub repository through the website, without adding an initial README, license or gitignore. From the local package repository, replace YOUR_GITHUB_USERNAME and run:

git remote add origin https://github.com/YOUR_GITHUB_USERNAME/hcphases.git
git remote -v
git push -u origin main

Authenticate when Git requests it, using a browser/credential manager or your configured SSH credentials. Do not put a token in a repository file or remote URL. After the automated Windows checks pass, create a version tag and push it:

git tag -a v0.3.2 -m "hcphases 0.3.2"
git push origin v0.3.2

In GitHub’s Releases page, create a release from that existing tag. For this early 0.x software, marking the initial release as a pre-release is appropriate. Attach the verified wheel, source distribution and checksum file; optionally add the complete HTML documentation archive. A PyPI upload is a separate operation. Add actual repository/documentation URLs to metadata once the remote exists.

Ongoing work

Before editing, use git status and git pull –ff-only if changes may have been pushed elsewhere. After tests and review:

git status
git diff
git add src docs tests examples tools pyproject.toml uv.lock CHANGELOG.md CITATION.cff
git diff --cached
git commit -m "Describe the concrete change"
git push

Only staged files enter the commit; untracked build output should stay ignored. Use feature branches and pull requests when collaboration warrants them. Routine commits need no new release tag. An installable update should receive a new version, checks and release artifacts; never move a published version tag.

A consuming research repository has independent commits and remotes. During development it may use an editable local checkout. A scientific campaign should instead record the exact wheel, dependencies, source commit and implementation hashes. Updating this repository does not update a consumer’s recorded run.