Developer workflow and release
==============================

Tools
-----

-  `cocogitto <https://github.com/cocogitto/cocogitto>`__ (``cog``) — conventional commits and ``CHANGELOG.md``
-  `prek <https://prek.j178.dev>`__ — git hooks (``prek.toml``)
-  `lychee <https://github.com/lycheeverse/lychee>`__ — link check on the assembled Pages tree
-  Org sources under ``docs/orgmode/`` (tutorial, howto, explanation, reference). ``scripts/build-docs.sh`` runs pandoc to rst, then Sphinx + **Shibuya** (``pixi r -e docs docbld``). Generated rst is not committed.
-  Pages serves that tree at ``/`` and ``/docs/`` (same HTML). ``website/`` is the old ox-html marketing page and is not deployed.

.. code:: bash

   prek install
   prek run -a
   cog check
   pixi r -e docs docbld
   scripts/export-landing.sh
   scripts/assemble-site.sh
   lychee --config lychee.toml '_site/**/*.html'

Refresh the documentation lock after changing ``pixi.toml`` ``[feature.docs]`` or ``docs/requirements.txt``:

.. code:: bash

   pixi lock

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

+------------------+---------------------------------------+--------------------------------------------+----------------------------------------------------------------------+
| Workflow         | File                                  | Trigger                                    | Purpose                                                              |
+==================+=======================================+============================================+======================================================================+
| Prek             | ``ci_prek.yml``                       | push, PR                                   | ``prek run -a``                                                      |
+------------------+---------------------------------------+--------------------------------------------+----------------------------------------------------------------------+
| Documentation    | ``ci_docs.yml``                       | push, PR                                   | Locked Sphinx HTML (``pixi.lock``) + assembled site + lychee         |
+------------------+---------------------------------------+--------------------------------------------+----------------------------------------------------------------------+
| Pages            | ``pages.yml``                         | push to main                               | Deploy site + locked Sphinx docs                                     |
+------------------+---------------------------------------+--------------------------------------------+----------------------------------------------------------------------+
| Lint             | ``lint.yml``                          | PR                                         | Conventional commits + large-file audit                              |
+------------------+---------------------------------------+--------------------------------------------+----------------------------------------------------------------------+
| Version lockstep | ``scripts/check_version_lockstep.sh`` | ``cargo test``                             | Cargo, Python, meson, pixi, Fortran, CITATION, Sphinx, core pin      |
+------------------+---------------------------------------+--------------------------------------------+----------------------------------------------------------------------+
| C/C++ dist       | ``ci_cxx.yml``                        | push, PR                                   | CMake/Meson/pkg-config without cbindgen; clib fixture gate           |
+------------------+---------------------------------------+--------------------------------------------+----------------------------------------------------------------------+
| crates.io        | ``crates_publish.yml``                | ``v*`` tag                                 | ``cargo publish --locked``                                           |
+------------------+---------------------------------------+--------------------------------------------+----------------------------------------------------------------------+
| Python wheels    | ``python-wheels.yml``                 | ``v*`` tag, PR                             | maturin matrix → PyPI                                                |
+------------------+---------------------------------------+--------------------------------------------+----------------------------------------------------------------------+
| cxx tarball      | ``cxx_tarball.yml``                   | GitHub Release                             | slim + vendor C/C++ source tarballs                                  |
+------------------+---------------------------------------+--------------------------------------------+----------------------------------------------------------------------+
| C ABI tarball    | ``c_lib_tarball.yml``                 | GitHub Release + ``workflow_dispatch`` tag | Attach prebuilt ``libreadcon_db`` (``readcon-db-clib-$VER-$target``) |
+------------------+---------------------------------------+--------------------------------------------+----------------------------------------------------------------------+

Release
-------

.. code:: text

   scripts/release-prep.sh X.Y.Z
         │  prek, sphinx + lychee, version bump, cog CHANGELOG, cxx-dist + clib gate
         ▼
   commit: maint: bump to vX.Y.Z   ──►  open Pull Request to main
         ▼
   merge PR to main  ──►  git tag -s vX.Y.Z && git push origin vX.Y.Z
         │
         ├─► workflow "Publish to crates.io": cargo publish --locked
         ├─► workflow "Python wheels": maturin matrix → PyPI
         ├─► workflow "cxx source tarball": after a GitHub Release exists
         └─► workflow "C ABI library tarball": prebuilt clib (or dispatch tag later)

Attach prebuilt C ABI to an existing tag: Actions → **C ABI library tarball** → ``tag=vX.Y.Z`` on a branch that has ``scripts/package-clib.sh``.

.. code:: bash

   prek run -a
   pixi r -e docs docbld
   scripts/export-landing.sh
   scripts/assemble-site.sh
   lychee --config lychee.toml '_site/**/*.html'
   scripts/release-prep.sh X.Y.Z
   git commit -m "maint: bump to vX.Y.Z"
   # open PR, merge, then:
   git checkout main && git pull
   git tag -s vX.Y.Z -m "vX.Y.Z"
   git push origin vX.Y.Z

Do not hand-edit the generated ``CHANGELOG.md`` section. Extend ``cog.toml`` ``[commit_types]`` if a historical type blocks ``cog changelog``. Push only the version tag (``git push origin vX.Y.Z``), not every local tag.

Fair-campaign freeze check (does not re-run the campaign):

.. code:: bash

   python paper/cpc/scripts/gen_fair_table.py --check