# 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
- 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.

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

```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

```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`.

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

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