Deployment
==========

This page describes how VANE's artefacts are built and published by continuous
integration.

Continuous integration
----------------------

Every push and pull request to ``main`` or ``develop`` runs the ``CI`` workflow:

* **Lint & type check** — installs the package from its metadata
  (``pip install -e ".[dev]"``), then runs ``ruff check``, ``ruff format --check``,
  and ``mypy src/``.
* **Tests** — installs ``.[dev]`` and runs ``pytest`` with the coverage gate on
  Python 3.10, 3.11, and 3.12.
* **PR review summary** — posts a checklist of the check results on pull requests.

Documentation
-------------

The ``Docs`` workflow builds the Sphinx site with warnings treated as errors
(``sphinx-build -W -b html docs docs/_build/html``) on every push and pull request,
and uploads the built HTML as a workflow artifact. To build locally:

.. code-block:: bash

   pip install -e ".[docs]"
   sphinx-build -b html docs docs/_build/html
   # open docs/_build/html/index.html

Package publishing
------------------

Pushing a ``vX.Y.Z`` tag triggers the ``Publish`` workflow's **build** job, which
builds the wheel and source distribution (``python -m build``) and uploads them as a
workflow artifact. The **PyPI upload** runs only when the workflow is started manually
(``workflow_dispatch``) from the Actions tab, so tagging a release does not auto-upload
— the maintainer triggers the upload once PyPI trusted publishing is configured and
the release is intended. See :doc:`release_checklist` for the steps that lead up to a
tag.

Security scanning
-----------------

The ``Security`` workflow runs on every push and pull request and on a weekly
schedule. It has two parts with **different policies**:

* **bandit** — static security analysis of the source. This **gates** the workflow:
  a medium-or-higher severity, medium-or-higher confidence finding fails the job, so
  the green badge means the source is bandit-clean at that bar.
* **pip-audit** — a dependency vulnerability audit. During the alpha series this is
  **advisory** (``continue-on-error``): a vulnerability in a transitive dependency,
  which the project cannot fix directly, is surfaced in the logs without failing the
  badge. Reported advisories are reviewed and, where a direct dependency is affected,
  addressed by bumping the pinned floor in ``pyproject.toml``. The badge therefore
  reflects the **bandit** gate, not the dependency audit; consult the workflow logs
  for the current ``pip-audit`` findings.