Contributing

Publishing the documentation

Before you read: Contribution workflow, Releases and stability (what a pushed tag does — this page's § What happens at release time is its documentation half) and the generated vs hand-written table in Project structure.

Documentation in this repository is either generated from the code (and then checked by a gate) or written by hand (and then reviewed). This page explains which is which, how each is published, and what you have to do when your change affects documentation. After it you know, for any change, which generator to run and which files to commit with it.

Where it is published#

The site is served by GitHub Pages from the /docs directory of main, at https://angolardevops.github.io/delonix-runtime/. The Pages source setting itself lives in the repository settings, not in the tree; what the tree does contain is docs/.nojekyll, which turns Jekyll off so every file under docs/ is served exactly as committed.

A consequence worth knowing: because Jekyll is off, Markdown files under docs/ — including this handbook in docs/dev/ — are not rendered to HTML by Pages; they are served as plain files. The rendered view of the handbook is GitHub's own Markdown rendering when browsing the repository (docs/dev/README.md on github.com), which also renders the Mermaid diagrams. Links between handbook pages are relative, so they work in both places.

Who owns what#

The user site: docs/gen.py#

The reference pages embed the real --help of the delonix binary, captured when the generator runs, so the site never documents a flag that does not exist. The editorial content (introductions, examples, notes) lives in dictionaries inside docs/gen.py itself — edit it there, not in the HTML.

cargo build --release -p delonix-runtime-bin
python3 -m pip install markdown     # the generator renders ARCHITECTURE.md
python3 docs/gen.py                 # uses the tree's release binary by default
git diff --stat -- docs/

The generator also accepts the binary path as its first argument. Commit the regenerated files together with the CLI change that caused them. Two checks fail if you do not:

• the docs job in CI regenerates the site and fails when git diff -- docs/ is not empty; the same job validates every examples/*.yaml with stack apply --dry-run and stack validate, and checks the man pages generated by delonix man --dir <dir> --index with groff;
• the release workflow repeats the regeneration against the release build before publishing, so a tag whose site is out of date does not ship.

The command-citation gate: scripts/docs_cli_gate.py#

Every delonix … command quoted in a code context (<code>, <pre>, Markdown code fences, reST literal blocks, YAML comments) in the current documentation must resolve in the command tree of the binary built from the tree (read through scripts/cli-tree.sh). It runs in the cli-surface CI job:

cargo build --release -p delonix-runtime-bin
DELONIX_BIN="$PWD/target/release/delonix" python3 scripts/docs_cli_gate.py
python3 scripts/docs_cli_gate.py --list      # every citation and where it is

It exists because commands were removed in consecutive major releases and several current pages kept teaching unrecognized subcommand. Dated historical records — docs/releases/, docs/RELEASES.md, docs/discovery/ and the dated audit and measurement reports — are excluded on purpose: they must keep quoting the spelling of the version they describe. A citation that is wrong on purpose goes into scripts/docs_cli_allow.tsv with a reason.

The files it scans are listed in TARGETS at the top of the script. Check that list when you add a new documentation directory; a page outside it is not checked.

The handbook's facts: scripts/dev_docs.py#

The structural facts in docs/dev/ — the crates and their layers, the dependency graph, the binaries, the pinned toolchain and the CI jobs — are generated from Cargo.toml, scripts/arch_fitness.py, rust-toolchain.toml and .github/workflows/ci.yml. In a page they sit between markers:

<!-- dev-docs:begin <key> -->
…generated, do not edit…
<!-- dev-docs:end <key> -->

python3 scripts/dev_docs.py            # rewrite every generated region
python3 scripts/dev_docs.py --check    # exit 1 when docs/dev is stale (CI job `arch`)

Rules:

• Never edit inside a region. The next regeneration overwrites it and --check fails in CI. If a fact is wrong, fix its source (Cargo.toml, the LAYERS table in arch_fitness.py, ci.yml) or the generator.
• Text outside the markers is never touched, so narrative can surround a generated table.
• A new region needs a render_* function, a key in regions() and a marker on a page, in the same commit.
• No numbers that change on every commit (lines, tests, commits) — not in the generator and not in the narrative. A gate that is red on every PR stops being read, and a hand-written count silently becomes false.

If your PR adds or moves a crate, changes a dependency between crates, adds a binary, bumps the toolchain or changes a CI job, run python3 scripts/dev_docs.py and commit the result with it.

What happens at release time#

The release workflow (.github/workflows/release.yml) runs when someone asks for it (gh workflow run release.yml -f tag=v4.4.0) — a pushed tag alone does nothing. For documentation it:

1. regenerates the user site against the release build and fails if docs/ differs;
2. publishes the GitHub Release with docs/releases/<tag>.md as its notes (or generated notes when that file does not exist);
3. checks out main, runs scripts/gen-releases.sh (the docs/RELEASES.md appendix) and scripts/dev_docs.py (the handbook facts), and commits both to main with [skip ci] when they changed.

The narrative of the handbook is not regenerated by CI. After a release has been published and validated, a maintainer-run review step reads the changes between the previous and the new tag together with the release notes, updates only the handbook pages those changes affect, and opens a pull request for it. When nothing structural or procedural changed, the outcome of that review is "nothing to update", stated explicitly.

What this means for your pull request#

Next: Cloud native standards, layer by layer — the reference part: each cloud native standard, what it requires, and the engine's conformance with dates.