I need to make a release

CNA snapshot 3b43bd86  ·  Development › Maintainer Handbook  ·  source links pinned to 3b43bd86

This page is a checklist for a human maintainer cutting a CNA release, grounded in what the TARGET tree at 3b43bd86 actually contains: where the version lives, what is generated from it, what a release entry has to record, how the sibling checkouts are now required rather than only recorded, and which numbers are deliberately not the product version. It marks each step as automated by the repository, manual, or not established in the source. CNA has a documented tag-and-changelog procedure and no release automation; nothing here was run. The user-facing account of the tags is on Releases & versioning.

Owner and read first

The version is decided in exactly one place, the root CMakeLists.txt: project(CNA VERSION 0.1.0 LANGUAGES CXX) supplies the numeric components (CMake's VERSION accepts numbers only) and set(CNA_VERSION_PRERELEASE "") supplies the pre-release identifier, empty on a final release, joined into CNA_VERSION_STRING. The pre-release identifier is deliberately a normal variable, not a cache entry, so an existing build directory cannot keep reporting the previous release after a bump. Read, in order:

1. docs/releasing.md: the procedure, marked “Current as of 0.1.0”; it is the only written process and this page follows it.
2. cmake/Version.cmake and Version.hpp.in: how the single decision becomes <build>/generated/include/CNA/Version.hpp.
3. cmake/DependencyVersions.cmake: the sibling versions a release requires and the configure-time check that enforces them.
4. CHANGELOG.md: its format, the [Unreleased] section, the [0.1.0] entry as the current template, and the link definitions at the bottom.
5. abi.h, ABI_VERSIONING.md and RELEASE_GATE.md: the independent C ABI version and its own gate.

Four numbers that are not one number

The siblings sharp-runtime, easy-gl and meta-gl and every external language binding have their own versions and cadence. The generated header exposes CNA_VERSION_MAJOR/MINOR/PATCH (preprocessor-testable literals), CNA_VERSION_PRERELEASE (without the leading -, empty on a final release), CNA_VERSION_STRING, and the constexpr functions CNA::getVersionMajor(), getVersionMinor(), getVersionPatch(), getVersionPreRelease(), getVersionString() and isPreReleaseVersion(). Consumers that derive from it: CMake consumers through CNA_VERSION, Apple bundles through CNA_APPLE_BUNDLE_VERSION (a cache entry defaulting to PROJECT_VERSION, the numeric components only, because a bundle version cannot carry a pre-release identifier), the configure banner (CNA: version …) and the Inspector's hello message (cnaVersion).

What a release promises, and what it does not

• Semantic Versioning, pre-1.0. CHANGELOG.md and docs/releasing.md state that while the major version is 0, a minor bump may change the public API; pre-release identifiers run alpha.N, beta.N, rc.N, ordered as SemVer orders them, and 0.1.0-alpha.1 precedes 0.1.0.
• A release is a Git tag plus a changelog entry. There is no separate release branch and nothing is published to a package registry. The local tag list holds three tags: v0.1.0-alpha.1 (2026-08-20), v0.1.0 (2026-10-10, an annotated tag “CNA 0.1.0” on the commit chore(release): prepare v0.1.0) and the audit-2026-07-complete marker. No workflow triggers on tags or uploads a release artifact. Whether a GitHub Release object exists is not recorded in the source.
• Uneven by design. The 0.1.0 entry's known limitations say pre-release quality remains: a minor release may change the public API, renderer coverage is uneven by design, the known per-renderer bugs are in NEXT.md §5 (a file no longer in the tree at TARGET), and “Content has no general .xnb reader”. A release does not promise that every renderer, platform or binding works. The last clause is narrower than it reads: CNA registers a set of built-in XNB readers by canonical name (see XNB content), so copy the claim into new release notes only with that qualification (read from CHANGELOG.md at 3b43bd86; not executed).
• No promise about the C ABI. The C ABI has its own gate, which reads “Not ready” at TARGET, and its 0.x minors have moved four times since the 0.1.0 tag (0.46.0 to 0.50.0; version history). Bindings are separate projects that each target one ABI generation and are not qualified against the snapshot (C API internals).
• What is not established. The sources say nothing about a support window, a deprecation policy, signed or binary artifacts, or which CI workflows must pass before a tag. Do not add such claims to release notes.

Checklist

“Repo” means the repository automates or checks it; “manual” means a person edits or runs it; “not established” means the source does not say.

Anatomy of a changelog entry

The format follows Keep a Changelog. Two release entries exist in CHANGELOG.md: ## [0.1.0-alpha.1] — 2026-08-20, which named a state of develop rather than a delta, and ## [0.1.0] — 2026-10-10, the first delta entry and the template to follow. The 0.1.0 entry has these parts, in order:

1. A short statement of what the entry describes: where it was cut from and that its lists are the changes since the previous tag.
2. Dependencies: a table of the three siblings with the required version and the tag and commit each was verified against, then a pointer to the submodule gitlinks and GIT_TAG values that pin everything else.
3. Added, Removed, Changed and Fixed, with concrete surface, the reason for each decision, and links to the documents that define them.
4. Known limitations, stated as limits rather than as a roadmap, including the tests that failed in the release tree before the release and are carried rather than fixed.
5. Verification: the configuration that was built, its build and test counts, every failure with its explanation, and the toolchain and sibling tags it ran against.
6. Link definitions at the bottom: [Unreleased] as a compare against the latest tag, the release as a compare against the previous tag, and releases/tag for the first one, all under libcna/cna.

The [Unreleased] section uses Changed, Removed and Fixed at TARGET. Several of its entries are written as records of why a decision was made (for instance the renderer retirement with its permanently reserved C ABI values, or the C++ ABI break with the overrides an IPlatform implementation must rename), which is the level of evidence a release entry should keep.

Verify the tagged tree

None of these were run for this page. They are the checks the sources imply once a tag exists:

git describe --tags                         # the tag name, or tag-N-g<hash> after it
git rev-parse 'vX.Y.Z^{commit}'             # the commit the tag names
cmake -S . -B <build> ...                    # the banner prints "CNA: version X.Y.Z[-pre]"
                                            # and one accepted-version line per sibling
grep CNA_VERSION_STRING <build>/generated/include/CNA/Version.hpp

Then run the structural VersionTest.* cases through the core test binary and, if the C API is part of the claim, build it in a separate CNA_BUILD_C_API=ON tree and run ctest -R '^CApi'. Both installed CMake packages named CNA, the C API's and the C++ SDK's (CNA_INSTALL_CXX), take their package version from abi.h, not from the product version, so find_package(CNA 0.1 CONFIG) compares against the C ABI (0.50.0 at TARGET) and a request written as “0.1” is not a statement about the product release.

Traps

• Two trees, one string. Until step 1 is done, every snapshot after the tag reports 0.1.0, including trees whose C++ ABI no longer matches the release. Record git rev-parse HEAD in bug reports and evidence, not the version.
• Numbers you cannot bump together. Raising the product version does not touch the ABI version, and a C ABI step does not need a product release. Do not describe either as implying the other.
• A sibling the check does not pin. The configure-time check accepts any later patch release of the required minor line and compares versions, not commits, and CNA_CHECK_DEPENDENCY_VERSIONS=OFF turns it into a warning. A reproducible release still needs the exact sibling commits in its Dependencies table.
• Pointing links at a moving branch. A branch head moves past the tag; release notes and documentation should link a tag or a commit permalink.
• Pre-release identifiers and Apple. A bundle version cannot contain a pre-release identifier such as -beta.1, which is why CNA_APPLE_BUNDLE_VERSION defaults to the numeric components.
• A reconstructed changelog is a claim. State counts and capabilities from the tree at the tag, not from the previous entry; see Known uncertainty and history.

Review checklist

• One source of truth edited; Doxyfile, changelog and README copies agree with it; the configure banner prints the intended string.
• The changelog entry describes the changes since the previous tag, carries the Dependencies table with the sibling versions and commits, and mentions the C ABI version and any ABI step since the previous release.
• The Verification section names the configuration, the test counts and every failure; steps marked not established are stated as such in the release notes rather than implied.
• The tag is annotated, on the intended branch, and pushed explicitly, with owner approval.
• Bindings, samples and the documentation pin are told which revision to expect.

Related: Maintenance and pin policy, Blast radius and readiness and Change build configuration.