Docs · Internals
How a change reaches a release
Every pull request to the nexus repository goes through the same gates, and a version tag turns into release archives and published crates. This diagram follows the workflows as they are written.
What it does
On every push or pull request: formatting and diagram-index check, clippy with warnings denied, a test matrix on Linux, macOS and Windows, documentation, and a build at the minimum supported Rust version, 1.88.
On pull requests, a drift check refuses a change to a file owned by a diagram unless the diagram changed too, or a commit trailer says why not.
A tag starting with v creates the GitHub release with a generated changelog, builds Linux, macOS and Windows archives, publishes the crates and updates the version branch.
The diagram
Drag to move. Pinch, Ctrl + wheel or the + and - keys to zoom; arrow keys to move; 0 to fit; double-click to fit. Select a node to light up its links.
Text description of the diagram
Flow diagram in two parts. Pull request or push: a push starts the fmt job and, on pull requests only, the diagram-drift job. After fmt come clippy, the test matrix, the documentation build and the minimum-version build. All of them, with diagram-drift, feed a gate named CI Success. The test matrix also feeds coverage, which goes to Codecov: project coverage is informational and patch coverage blocks at 80 percent. A security audit with cargo-deny is advisory. Release: a tag starting with v generates the changelog, creates the GitHub release and builds archives for Linux x64 and ARM64, macOS x64 and ARM64 and Windows x64, which are uploaded to the release. The release also publishes the crates nexus-claude then claude-code-api, and updates the version branch.
Guided reading
Step 1. fmt
rustfmt in check mode, and a check that the diagram index is derived from the diagram headers and is current.
Step 2. diagram-drift (pull requests only)
If a changed file is covered by a diagram, the same pull request must change that diagram, or one of its commits must carry a Diagram-Unchanged trailer with a reason. It is skipped on pushes, where there is no branch to compare.
Step 3. clippy, tests, docs, minimum version
Clippy denies warnings. The test matrix runs Ubuntu, macOS and Windows on stable and beta, plus nightly on Ubuntu as advisory. Documentation builds with warnings denied. The crate must build with Rust 1.88.
Step 4. CI Success
The required gate waits for fmt, diagram-drift (or its skip), clippy, test, docs and the minimum-version build. Coverage and the security audit are not part of it.
Step 5. Coverage
cargo llvm-cov feeds Codecov. The project figure is informational. The patch gate blocks: lines changed by a pull request must be at least 80 percent covered.
Step 6. Release
A tag starting with v generates the changelog and creates the GitHub release, builds archives (tar.gz for Linux and macOS, zip for Windows) and uploads them, publishes nexus-claude then claude-code-api to crates.io, and updates the version branch.
Why it is built this way
CI keeps the diagrams honest
The drift check forces the question of whether a diagram still holds each time its code changes. It does not prove that the diagram is accurate, only that someone looked.
Advisory where the signal is noisy
The nightly compiler is prone to internal errors unrelated to the code, so it cannot block. The dependency audit is advisory for now.
Patch coverage blocks, project coverage informs
The project figure is informational until the baseline is raised. Holding every new change to the bar still moves it in the right direction.
A hung test is cut off
The test job has a 30 minute timeout. A past hang on Windows left a job silent for almost an hour before it was cancelled by hand.
Public sources
Where to check each statement, in the public repositories.