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

Releases are cut from ``develop`` into ``main`` and tagged. Each tagged ``v*`` triggers
the publish workflow.

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

#. **Green integration branch.** ``develop`` passes lint, type check, and tests on
   Python 3.10–3.12.
#. **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 -b html docs docs/_build/html`` succeeds with
   no warnings.
#. **Validation matrix current.** :doc:`../user_guide/validation_matrix` reflects the
   shipped behaviour.

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

#. Open a release pull request from ``develop`` into ``main``.
#. Wait for all checks to pass.
#. Merge with a merge commit (releases are merge commits into ``main``, not squashes).
#. Tag the merge commit ``vX.Y.Z`` and push 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.