Working on CNA

CNA snapshot 009d40f5  ·  Development › Workflows  ·  source links pinned to 009d40f5

Each workflow below turns an unfamiliar symptom or idea into a small, reviewable change with explicit cross-platform validation. They are the manual engineering loops behind the recipes in the Maintainer Handbook, tied to what CNA's repository actually contains at snapshot 009d40f5: its instruction files (AGENTS.md and CLAUDE.md), its presets, its gates and its twenty CI workflow files. Names of tests, scripts and workflows were read in the source; none was run for this page.

Fixing a bug

1. Classify the failing boundary. Runtime scheduling, platform event or service, shared graphics state, renderer translation, content, audio or ABI. The change map names the owner for each, and the debugging cookbook the probes.
2. Reproduce at the narrowest level. Save the exact backend axes and the build: the configure line or preset, the platform, audio and renderer identities, and the failing test name. Prefer a focused executable (the unit presets) or a HEADLESS or SOFTWARE configuration over a windowed one, and confirm the test is registered with ctest -N.
3. Trace from public observation backward. Find the declaration, the implementation, the factory or registry that creates it and the tests, and write the five-line trace (caller, boundary, callee, owner, test) described under Debugging unfamiliar code.
4. Add a failing test beside the owning module (modules/<name>/tests, mirroring the namespace path), or in a conformance suite when several implementations share the promise: PlatformConformance and PlatformWindowConformance run once per compiled platform, AudioDeviceConformanceTests once per audio device, the cross-renderer contracts in a multi-renderer build, the shared parity fixtures across renderer families, and the XNA oracle corpus for XNA-visible behaviour. Make sure the test can actually reach its assertions: a test that aborts before its first check, or dies on a graphics-profile refusal, reads as red and proves nothing (profile_dead_tests.py names such failures after a private-display run). CNA's instructions also require tests to land in the same task as the code: a test that existed before an implementation does not count.
5. Change the smallest owner. Do not fix one backend if the wrong assumption lives in shared code, and do not push a backend quirk into shared code. Where CNA and FNA disagree on behaviour, CNA follows measured XNA, and a divergence taken on those grounds is recorded with a comment naming the XNA IL that settles it and a row in plan_bindings_upstream.md.
6. Validate focused, then sanitizer, then the affected matrix. The focused executable or preset; a sanitizer build of the area where lifetime or threading is involved (sanitizer recipe); then the tuples and hosts the change can reach (What to test after changing X). Say which platform, audio and renderer combinations were not exercised.
7. Review lifetime and the other backends before declaring success: the invariants and the questions under Review your own change.

Adding a feature

First decide whether it is public CNA behaviour or an implementation capability. A public surface belongs in the owning module and carries API and ABI, documentation, tests, examples and binding consequences: XNA-shaped names and semantics where compatibility is intended, the CNAEXT marker (and the EXT naming) for anything that is not XNA 4.0, a row in the C API mapping, and an example in the module's examples/ where the module has them. A renderer or platform capability needs neutral semantics and truthful support reporting: a capability enumerator or service, an opt-in answer that defaults to false where the shared default would otherwise say true (truthful capabilities), and an explicit refusal where it is unsupported. Inventory every implementation before editing the interface (25 renderer identities, 7 platforms, 4 audio implementations; the generated Selection axes index lists them). Unsupported is better than a silent no-op, and a feature that only one family implements must say so through a capability query, not through its absence from a table.

Two repository rules are easy to miss. New shader-based engine-layer code asks the capability and the matching query (for example ExecutesShaderEffectSourceEXT()). And the CNA_CNAEXT layer's files must all be wrapped in #ifdef CNA_CNAEXT, which the CNAEXT_GuardDiscipline test enforces.

Modifying public API

• Keep XNA-shaped naming and semantics where compatibility is intentional. Exact XNA names in the matching Microsoft::Xna::Framework namespace, C# properties as getXProperty() and setXProperty(), SharpRuntime aliases for primitive types; details on Conventions.
• Add Doxygen on exported public declarations in the /** @brief ... */ block form; the engine layer has a test for it, the rest is a review rule.
• Search uses in samples, tests and downstream modules: the include roots mirror the namespace path, so a rename touches every consumer spelling.
• Assess source compatibility, binary layout, export visibility and the experimental C API. A new public C++ symbol without a C ABI mapping makes the coverage gate stale (CApiCoverageMatrix), a layout or constant change is measured by CApiAbiHeaderBaseline against tools/c-api/abi_baseline.json, headers must still compile in every declared language mode (CApiHeaderCompatibility), and the version policy is ABI_VERSIONING.md. The ABI is 0.29.0 at this snapshot and experimental.
• Update language bindings only after pinning their compatible native version. The bindings are separate repositories that pin an ABI generation (0.21 at this snapshot), none qualified against 0.29.0: see the bindings table.
• Add compile-level consumer tests plus behaviour tests. The input module has PublicApiInputCompileTests and PublicApiInputSignatureFreezeTests; the strict-XNA purity check (StrictXnaApiSurfaceCheck_Compile_Run and its must-fail-to-compile counterpart) covers the Devices surface; the minimal-link probes in tests/modules fix each module's dependency closure.

Working on a renderer

1. Select the public renderer identity and find its descriptor and factory. RendererRegistry.cmake maps identity to family; the family's GetDescriptor() and create live under modules/renderers/<family>/src/ (Renderer selection internals).
2. Trace one known-good frame: create, begin, resource and state commands, present, destroy (Indexed draw trace, then the family's page from Graphics backends).
3. Identify the shared graphics contract and the backend-native translation point. The contract is IGraphicsRenderer and its resource interfaces; the translation is inside the family.
4. Add a conformance case independent of native details: a shared parity fixture (modules/graphics/examples/parity), a case in the cross-renderer contract suite, or a neutral test in modules/graphics/tests, so the promise is asserted for every renderer that makes it.
5. Run through the private display with native validation enabled. tools/platform/run_gpu_tests_private.sh <build-dir> -R '^Vulkan_' -j6 is CNA's own example; it refuses a build tree that forces a display. Validation switches per family are in the debugging cookbook, and Vulkan and OpenGL4 tests fail on their validation-output gates.
6. Compare another renderer and test resize, minimize and dispose, on a host capable of that native API. CNA's own guidance is to keep WebGPU changes renderer-local unless a common-interface change is genuinely required and verified across the existing renderers.

Before pushing, run the identity, combination, discipline and descriptor checks the multi-renderer workflow runs (check_renderer_identities.py, check_renderer_combinations.py, check_runtime_renderer_discipline.py, check_renderer_target_discipline.py, check_renderer_descriptors.py). No workflow names WEBGPU, SDL_GPU, OPENGL4, FNA3D, PORTABLEGL, FREEDIRECT or DIRECTX9, so for those families the local run is the only evidence. Recipe: Fix a renderer bug.

Working on a platform

1. Read IPlatform and the relevant narrow service contract (IPlatform.hpp, PlatformCapabilities.hpp, the interfaces under CNA/Platform/ and CNA/Platform/Input/). New production code uses these and never calls SDL directly outside the declared native edges.
2. Trace factory selection, service acquisition and refcounting, and the event pump. PlatformFactory::Create builds an implementation by name; AcquireSubsystem and ReleaseSubsystem are refcounted (PlatformConformance.SubsystemsAreRefcounted); PollEvents runs once per frame and fills a caller-owned batch.
3. Map native events to platform-neutral values before input code. A backend alone owns native key codes, pointer coordinates and device state; the input module sees only PlatformEvent values and snapshot services.
4. Keep native handles inside the capability interfaces renderers use (IPlatformGlContext, IPlatformVulkanSurface, NativeWindowHandle, the surface presenter), and keep a service non-null exactly when its capability is true.
5. Run the platform source gates, the focused contract tests and native-host CI. The gates CNA's instructions list are tools/platform/sdl_inventory.py --check, sdl_classify.py --check, renderer_sdl_audit.py --check, sdl_ratchet.py --check and hot_path_lint.py; the platform workflow adds --strict, nonproduction_sdl_audit.py and check_contract.py. The focused tests are the CnaPlatformTests, CnaPlatformWindowTests and GameEventSemanticsGoldenTest runs; the native-host jobs are in platform-ci.yml. The native X11 backend has its own entries (CnaX11MappingTests and siblings) and the Wayland backend its protocol, portal and compositor entries; none of the Wayland entries runs in a workflow.

Recipe: Modify a platform backend; backend pages start at Platform backends.

Adding tests

Use module tests for isolated behaviour and the cross-module or conformance roots for promises shared by implementations. Reuse deterministic fixtures. Include a negative or destruction case where ownership is involved, and confirm that CTest registers the new test and that the responsible CI workflow runs it. Concretely at this snapshot:

• Where. modules/<module>/tests/ mirrors the namespace path and is globbed into the module's object group (UnitTests.cmake), which feeds both CnaTests and the focused executable. Fixture assets and the cross-module probes live under top-level tests.
• Doubles. Consumer tests use canned platform services (for example CannedKeyboard.hpp and CannedMouse.hpp under the platform tests) or the parameterised conformance suite, not native event injection; a genuinely backend-specific test belongs with that backend.
• Registration and gating. A test can also be registered explicitly with a label, timeout and environment through cna_register_renderer_test in TestHelpers.cmake. A test that exits 77 is skipped, not passed; window tests need a private display; and in configurations that compile Vulkan or OpenGL4 a test fails on validation or GL-error output.
• Rules for XNA API tests. Every public method, constructor, operator and constant needs at least one test; out-ref overloads and static factories are tested separately; equality, ToString() and GetHashCode() have their own cases.
• Which workflow runs it. See Which workflow will see your change; a test in a suite that no configuration builds runs nowhere.

Recipe: Add a regression test; architecture of the test targets: Test architecture and change recipes.

Debugging unfamiliar code

# declaration and definition
rg -n "class GraphicsDevice|GraphicsDevice::Present" modules
# creation/registration, not just uses
rg -n "GraphicsDevice|Register|Descriptor|Factory" modules cmake
# tests and build ownership
rg -n "Present|GraphicsDevice" modules/*/tests tests
rg -n "GraphicsDevice" --glob 'CMakeLists.txt' --glob '*.cmake'

Run them at the revision you are documenting: with plain git, git grep -n "PlatformInputBridge::ProcessEvent" 009d40f5dd085c4e674d3479675fac84b12b3e0a -- modules searches the snapshot regardless of what your working tree has checked out. Write a five-line trace in your notes (caller, boundary, callee, owner, test) before editing, which prevents local code familiarity from replacing system understanding. A filled-in example for a present call:

The method behind the trace is in How to understand code you did not write, and the map of what to read is the change map. CNA's own repository instructions are AGENTS.md and CLAUDE.md; they describe how CNA itself is developed and are stated in the next sections, but they can lag the CMake and the source, so verify a rule against the file it names.

Review your own change

• Does the change live in the owner named by the architecture (the row in the change map)?
• Did a claimed backend or capability become dishonest, or a default of true get inherited by a renderer that cannot do it?
• Can destruction happen with partial initialization or repeated dispose, and does the platform-outlives-dependents rule still hold after any member reorder?
• Did thread affinity or callback constraints change (Thread and callback map)?
• Which focused test failed before and passes now?
• Which platform, renderer, audio and binding was not exercised, and is that explicit in the description? A workflow file is configuration, not a result.

The self-review questions extend this list for large, machine-written patches.

Commits, task records and reports

CNA has no CONTRIBUTING file, pull-request template or code-of-conduct file at this snapshot (the only directory under .github is workflows); the working conventions are in its instruction files and plan ledgers, and the Git history follows them. They are written for whoever changes the code, including automated coding assistants, and they describe how CNA itself is developed, so they are also a fair review standard for a human patch.

• One task, one commit, committed when finished. Create the commit as soon as the task is done (build verified, tests passing, the plan, AUDIT.md and NEXT.md updated); do not push unless the maintainer asks. Stage only the files that belong to the task, by explicit name: never git add -A or git add ., because the repository routinely has unrelated local changes. Do not bundle unrelated tasks.
• Messages name the task. The form is <type>(Task <ID>): <what changed and why>, for example fix(Task STREETS-0008): SDL_GPU saturates the unlit diffuse colour at the vertex, as Direct3D 9 does; a range is written fix(Tasks WGF-0001..0007): .... The types in use are fix, feat, test, docs, refactor, perf, build, ci, chore, revert, plan and spike, plus merge(<Campaign>).
• Campaigns and task records. Work is organised in campaigns, each with a branch cut from next and a plan file in the plans directory that acts as its evidence ledger: task IDs with a fixed prefix (for example GTI-0001 in plan_gpu_test_isolation.md), one row per task, and each row carrying its own evidence, deviations and refusals rather than leaving them in a commit message. A finished campaign is integrated with a merge commit such as merge(OpenGL4ModernGraphics): integrate opengl4-modern-graphics into next. next is the integration branch; develop is the alpha.1 tag commit.
• Running ledgers. NEXT.md records what changed and the decisions that did not survive contact (dated entries are history, not current support); AUDIT.md tracks the XNA API audit and an API is not marked complete until its tests are; CHECKLIST.md is the per-file porting checklist (SPDX header, Doxygen, API surface compared against the XNA reference assemblies and not only FNA, tests).
• The task report. State the changed files, added stubs, missing dependencies, intentional deviations, the build result and the remaining errors. Build the affected target (there is no buildable CNA target; build the configuration or a target by its own name).
• Environment rules. Never run window or GPU tests on the live desktop; use stable in-repo cmake-build-<variant>/ directories with ccache rather than scratch directories; build parallelism is uncapped and memory is the constraint. These are stated in Getting started.

Which workflow will see your change

CNA has twenty workflow files at this snapshot. Seventeen run on pushes and pull requests to next, develop and main (several only for changes under listed paths); the rest are manual. A workflow is configuration, not a result, and this table records what each is configured to run, not whether it passed.

Most Linux workflows clone the sibling repositories with clone_siblings.sh, which takes the first of the pushed, source or target branch that exists in each, then next, then develop. The Apple, Emscripten, devices and content-pipeline workflows instead check out sharp-runtime at a fixed commit, and static reading of those files suggests that some pin a revision older than the snapshot needs, so a red or green run there is not by itself evidence about next. A local run that needs a particular sibling revision must set it up by hand.