Release checklist
=================

Releases are tagged on ``main``. Tagging ``v*`` triggers the **build** job of the
``Publish`` workflow, which uploads the wheel and sdist as a workflow artifact; the
PyPI upload is a separate, manual step (see *Post-release* and :doc:`deployment`).

Pre-release
-----------

#. **Green main.** ``main`` passes lint, type check, tests (Python 3.10–3.12), the
   documentation build, and the security scan.
#. **Changelog finalised.** Move the accumulated ``[Unreleased]`` entries under a new
   ``[X.Y.Z] - YYYY-MM-DD`` heading and leave a fresh ``[Unreleased]`` section.
#. **Version bumped.** Update ``version`` in ``pyproject.toml`` to ``X.Y.Z``.
#. **Examples verified.** The OpenFAST examples import against the current public API,
   and ``examples/synthetic_quickstart.py`` runs end to end.
#. **Docs build clean.** ``sphinx-build -W -b html docs docs/_build/html`` succeeds.
#. **Validation matrix current.** :doc:`../user_guide/validation_matrix` reflects the
   shipped behaviour.

Cutting the release
-------------------

#. Land the changelog finalisation and version bump on ``main`` through a normal pull
   request, and wait for all checks to pass.
#. Tag the release commit on ``main`` as ``vX.Y.Z`` and push the tag (for example by
   publishing a GitHub release, which creates the tag).

Post-release
------------

#. Confirm the ``Publish`` workflow's **build** job produced the wheel and sdist
   artifact for the tag.
#. When the upload is intended, run the ``Publish`` workflow **manually**
   (``workflow_dispatch``), selecting the release tag ``vX.Y.Z`` as the ref ("Use
   workflow from → Tags → vX.Y.Z"), so it builds and uploads **exactly the tagged
   commit** rather than whatever the default branch currently points at. Tagging alone
   does not upload, and this requires PyPI trusted publishing to be configured.
#. Confirm the documentation built without warnings.
#. Open a GitHub release with the changelog section as the notes.

Versioning
----------

VANE follows `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_. During the
alpha series the API may change between minor versions; from the first tagged release,
breaking changes increment the major version (or the minor version while
``0.y.z``), and are always recorded in the changelog.