Developer workflow and release#

Tools#

cocogitto (cog) — conventional commits and CHANGELOG.md
prek — git hooks (prek.toml)
lychee — link check on the assembled Pages tree
Sphinx + Shibuya (pixi.toml [feature.docs], locked by pixi.lock) — pixi r -e docs docbld
Pages serves that tree at / and /docs/ (same HTML). website/ is the old ox-html marketing page and is not deployed.

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:

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#

  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.

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):

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