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:

.. code-block:: console

   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:

.. code-block:: console

   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:

.. code-block:: console

   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:

.. code-block:: console

   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.