Maintainer Handbook
Evidence basis: source-verified at the pinned commit. Claims on this page were checked by reading the CNA source at commit 009d40f5; unless a sentence says otherwise, nothing here was built or executed. This hub organises the task pages; each recipe states its own evidence basis.
The Maintainer Handbook is organised around jobs, not chapters. Each recipe starts from something you need to do to CNA — fix a renderer bug, change a public XNA behaviour, add a regression test — and gives the owner, the first files to read, how to reproduce narrowly, the trap most likely to produce a locally passing but architecturally wrong change, and the evidence the change needs. Detail lives in the Architecture and Internals pages; recipes link there instead of repeating it.
Recipes
| I need to… | Start with | Main internals |
|---|---|---|
| Fix a renderer bug | Which identity, which family, which host — then a second backend to separate shared logic from one translation layer. | Selection, Draw path, the family page |
| Change public XNA behaviour | The XNA-shaped header, the owning module, the oracle and the C ABI consequence. | Runtime, GraphicsDevice |
| Modify a platform backend | The IPlatform contract, the sibling backends, and the conformance suite. | Platforms |
| Add a regression test | Which object group, which fixture, which CTest role, and how narrow the failing case can be. | Test architecture |
| Modify ContentManager | The load ladder, cache key, reader registry and unload semantics. | Content runtime |
| Modify the Content Pipeline | Importer, processor, writer and the golden round-trip; the pipeline must not need a device. | Content pipeline |
| Update the C API | Handle ownership, the error barrier, the ABI version and the binding pins. | C API internals |
| Debug shutdown and lifetime | The destruction order, borrowed pointers and callback barriers. | Shutdown, Ownership map |
| Investigate a sample failure | Separate a CNA defect from a sample, content, configuration or host problem. | Debugging cookbook |
| Change build configuration | Root options, the three selectors, presets and the configure-time refusals. | CMake architecture |
| Make a release | Version, ABI and changelog discipline, and what a release does and does not promise. | Releases & versioning |
| Update libcna.com after CNA changes | Advance the pin, recompute the canonical facts, re-audit the changed paths, regenerate the indexes and validate. | Maintenance & pin policy |
Anatomy of a recipe
- Find the owner of the behaviour: module, physical renderer family or platform backend, and whether the file is generated.
- Read first — the few files and symbols that establish the contract, in reading order.
- Reproduce narrowly — the smallest configuration (platform, audio, renderer axes) and the smallest failing test.
- Make the smallest change that preserves the invariant you identified.
- Prove it — the focused test, then a second independent backend or host, then the broader suite, and an honest note of what could not be run.
- Check the blast radius — other backends, the C ABI, bindings, build selection, generated files.
- Review checklist — what a human reviewer must be able to reconstruct from the diff alone.
Working references
- I want to change… — the one-table map from a kind of change to the first read and the trap.
- What to test after changing X — the change-to-test matrix, with the native-host caveats.
- Blast radius and readiness — how far a change of each class can reach.
- Architectural invariants, Conventions and Working on CNA.
- Testing, Debugging, and the generated test target index and CMake option index.
Related pages
The same subsystem is explained at four altitudes. These are the neighbouring pages at each one.
- User guide
- Building CNA · Verification & known issues
- Architecture
- Architecture maps
- Internals
- Internals
- Maintainer workflow
- Human Takeover · Working on CNA
- Tests and validation
- Testing
- Reference
- Generated references