Release and Publishing
======================

Versioning
----------

The canonical version lives in ``pyproject.toml`` and is mirrored by
``at_py.__version__``. Use Commitizen for release bumps so the version, tag, and
changelog stay aligned:

.. code-block:: bash

   cz bump --dry-run
   cz bump
   git push origin main
   git push origin vX.Y.Z

While the major version is ``0``, configured breaking changes bump the minor
version.

Artifacts
---------

Pushing a ``v*`` tag runs ``.github/workflows/release.yml``. The workflow builds
an sdist and wheel, checks them with Twine, and uploads them as the ``dist``
artifact. Tag pushes also create a GitHub Release and attach the checked
artifacts, publish the same checked distributions to PyPI, and smoke-test a
fresh install from PyPI.

PyPI Publishing
---------------

``at-py`` publishes to the ``oalib-at-py`` PyPI project from tagged releases
through Trusted Publishing. The repository stores no PyPI token.

The PyPI project must have a Trusted Publisher configured with these values:

* project name: ``oalib-at-py``
* owner: ``jgebbie``
* repository: ``at-py``
* workflow: ``release.yml`` (``.github/workflows/release.yml`` in this repo)
* environment: ``pypi``

After that setup, pushing a ``v*`` tag builds, checks, attaches, and publishes
the distributions.

Post-Release Verification
-------------------------

After pushing a tag, verify:

* the release workflow ``build``, ``publish-github-release``, ``publish-pypi``,
  and ``smoke-pypi`` jobs succeeded;
* the GitHub Release contains ``oalib_at_py-X.Y.Z-py3-none-any.whl`` and
  ``oalib_at_py-X.Y.Z.tar.gz``;
* the PyPI project page renders the README and shows the expected version;
* a clean environment can run ``python -m pip install oalib-at-py`` followed by
  ``python -c "import at_py; print(at_py.__version__)"``.

Hosted Docs
-----------

``.github/workflows/docs.yml`` builds and deploys Sphinx HTML to GitHub Pages on
pushes to ``main``.

GitHub Pages is configured to deploy from GitHub Actions at
``https://jgebbie.github.io/at-py/``. The workflow still checks Pages status
before upload so docs builds stay useful if Pages is ever disabled.