Skip to content

Contributing

Development setup

See Installation → Development setup for cloning, installing the dev dependency group, and running the editor frontend.

Tests and type checking

uv run pytest
uv run mypy src/nf_meta

Documentation

Docs sources live in docs/ on main, built with MkDocs (using the material theme) and mike for versioning.

uv sync --group docs
uv run mkdocs serve

The gh-pages branch is auto-generated by a workflow running mike. The workflow creates and updates it and it shares no history with the main branch. It must not be edited it by hand.

Deploying

  • Normal release → leave "Set as the latest release" ticked.
  • Backport release (publishing an older series) → untick it, or latest wrongly moves to the older series. To repair after the fact: open the release you actually want as latest and re-tick it there — that re-fires the workflow for the right series and fixes the alias. Unticking the wrong one does not move latest back by itself.
  • If a push to main and a release land close together, the second workflow run queues rather than racing (concurrency: docs-publish, cancel-in-progress: false) — a delay there is expected, not a failure.
  • A tag/release older than when mkdocs.yml was added will show the docs workflow run as skipped with a ::notice::, not failed red — expected.

If a deploy goes wrong

  • Check the run actually fetched gh-pages before calling mike (git fetch origin gh-pages:gh-pages step). If this step is ever missing or edited out, mike sees no prior versions and republishes a tree containing only the version it just built, wiping every other published version.
  • Check the released version didn't get the dev banner — NF_META_DOCS_IS_DEV should read false in that run's "Publish" step logs whenever a tag is present.