This guide documents the release flow for CDT++ release candidates and the final v1.0.0 release: prepare a dedicated release pull request, merge it, create an annotated tag with reviewed release notes, and create the GitHub release. The final stable release also includes the Zenodo deposit handoff prepared by issue #96, the publication sequence owned by issue #97, and the separate owner-timed stabilization and archival gate in issue #155.

CDT++ is not published to a package registry. The GitHub release and its automatically provided source archives are the release artifacts. The Python project and vcpkg manifest are repository tooling and dependency metadata; do not publish them independently as part of this process.

Conventions

Run the commands from the repository root. Set TAG for the release being made; the rest of the workflow is identical:

# The Git tag has a leading v; metadata versions do not.
TAG=v1.0.0
VERSION="${TAG#v}"
 
RELEASE_FLAGS=()
if [[ "$VERSION" == *-rc* ]]; then
  RELEASE_FLAGS+=(--prerelease)
fi

A release-candidate tag such as v1.0.0-rc3 uses 1.0.0-rc3 for product, vcpkg, Doxygen, and citation metadata, and the PEP 440 spelling 1.0.0rc3 for Python metadata. A stable tag such as v1.0.0 uses 1.0.0 everywhere else.

The changelog workflow requires the pinned git-cliff version declared by the Justfile. Check or install it with:

git-cliff --version

cargo install git-cliff --version "$(just --evaluate git_cliff_version)" --locked

Step 1: Prepare the release pull request

All feature and fix work intended for the release should already be on main. Keep the release pull request limited to release metadata, active release documentation, and its lockfile consequences.

Start from an up-to-date, clean main branch:

git remote -v
git switch main
git pull --ff-only
git status --short
git switch -c "release/$TAG"

The status command should produce no output before creating the branch.

Update release metadata

Edit the following synchronized metadata:

CMakeLists.txt: numeric project(... VERSION ...) and CDT_VERSION_SUFFIX; use an empty suffix for a stable release.
vcpkg.json: version.
pyproject.toml: [project] version, using the PEP 440 spelling.
docs/Doxyfile: PROJECT_NUMBER.
CITATION.cff: version and date-released.
README.md, REFERENCES.md, SECURITY.md, and .github/CONTRIBUTING.md: active release references and release-facing archival prose.
docs/RELEASING.md: current release command examples.

For v1.0.0, synchronize the versions in the repository before generating the changelog. Set CITATION.cff's date-released to the actual release date and review the other fields rather than rewriting unchanged metadata:

${EDITOR:-vi} \
  CMakeLists.txt \
  vcpkg.json \
  pyproject.toml \
  docs/Doxyfile \
  CITATION.cff \
  README.md \
  REFERENCES.md \
  SECURITY.md \
  .github/CONTRIBUTING.md \
  docs/RELEASING.md
 
uv lock
just changelog-unreleased "$TAG"

Review the citation identity fields at the same time: title, authors, ORCID, repository, URL, license, release date, and DOI. The top-level doi is the Zenodo concept DOI 10.5281/zenodo.21487043 for all CDT++ versions. Do not replace it with the RC3 record DOI or another version-specific DOI.

just changelog-unreleased validates TAG against all synchronized release metadata, runs git-cliff offline, takes the release date from CITATION.cff, and atomically replaces CHANGELOG.md. Review the generated release section before committing it.

Validate and commit the release metadata

Run the release-specific metadata check, strict documentation check, and full cross-platform-equivalent local validation gate:

just release-check
just docs-check
just ci

just release-check verifies synchronization across CMake, vcpkg, Python, uv.lock, Doxygen, citation metadata, and active release references.

The protected-branch ruleset uses stable summary contexts for the deterministic release gates:

build covers the Ubuntu GCC, Ubuntu Clang, macOS AppleClang, and Windows MSVC just ci matrix, the two Ubuntu parallel contracts, and the macOS viewer smoke contract.
build / AddressSanitizer + UndefinedBehaviorSanitizer and build / LeakSanitizer exercise the stable Linux sanitizer configurations.
CodeRabbit records the required review approval.

ThreadSanitizer and CodeQL remain advisory diagnostics rather than protected branch requirements; MemorySanitizer remains manual and experimental. Do not promote those contexts without a separate stability decision.

Review and commit only release artifacts:

git diff --check
git diff
 
git add \
  CMakeLists.txt \
  vcpkg.json \
  pyproject.toml \
  uv.lock \
  docs/Doxyfile \
  CITATION.cff \
  CHANGELOG.md \
  README.md \
  REFERENCES.md \
  SECURITY.md \
  .github/CONTRIBUTING.md \
  docs/RELEASING.md
 
git diff --cached --check
git diff --cached --stat
git commit -m "chore(release): release $TAG"

Refresh the stable archival provenance

For the final v1.0.0 release, regenerate the reference package only after the release metadata commit leaves the worktree clean. The generator records that clean commit as the producer revision:

test -z "$(git status --porcelain)"
just reference-regenerate
 
git diff -- reference/raw/v1 reference/manifests/v1
git add reference/raw/v1 reference/manifests/v1
git diff --cached --check
git diff --cached --stat
git commit -m "chore(release): refresh v1 reference provenance"
 
just reference-archive-check

Review and explain every changed exact field before committing the generated artifacts. The producer revision is the preceding clean release-metadata commit; the subsequent artifact commit cannot name itself without a self-reference. Both commits remain in the release pull request history, and the resulting merge commit containing both is the one that is tagged.

Push the branch and open the release pull request:

git push -u origin "release/$TAG"
 
gh pr create \
  --base main \
  --head "release/$TAG" \
  --title "chore(release): release $TAG" \
  --body "Finalize synchronized release metadata and the release date for $TAG. No feature work."
 
gh pr checks --watch

Merge the pull request only after every required check passes. Use the normal repository merge strategy; from the command line:

gh pr merge --merge

Step 2: Tag the merged release

Return to main, update it to the merge commit, and repeat the release gates against the exact commit that will be tagged:

TAG=v1.0.0
 
git switch main
git pull --ff-only
git status --short
 
just release-check
just docs-check
just ci
just reference-archive-check
 
test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
test -z "$(git status --porcelain)"
test -z "$(git tag -l "$TAG")"

Preview the annotated tag that will be created from the matching CHANGELOG.md section, then create and inspect it:

just tag-check "$TAG"
just tag "$TAG"
git tag -l --format='%(contents)' "$TAG"
git push origin "$TAG"

Both tag commands first run reference-archive-check, then reject malformed SemVer, missing or empty changelog sections, existing tags, and dirty worktrees. just tag-check performs every preflight without changing Git state. Do not move or replace a pushed release tag. If the tagged commit is wrong, prepare a new version instead.

Step 3: Publish and verify the release

Create the GitHub release from the annotated tag. RELEASE_FLAGS marks an RC as a prerelease and expands to no arguments for a stable release:

Before publishing a release that Zenodo should archive, sign in to Zenodo with the GitHub-linked account, enable this repository under Profile → GitHub, and verify that GitHub has exactly one active Zenodo release webhook without printing its token-bearing callback URL:

ZENODO_HOOK_COUNT="$(
  gh api repos/acgetchell/CDT-plusplus/hooks \
    --paginate \
    --slurp |
    jq '[.[][] | select(
      .active and
      (.events | index("release")) and
      (.config.url | startswith("https://zenodo.org/"))
    )] | length'
)"
test "$ZENODO_HOOK_COUNT" -eq 1

Stop if this preflight fails. Enabling Zenodo after publication does not reliably import an earlier GitHub release.

TAG=v1.0.0
RELEASE_FLAGS=()
 
gh release create "$TAG" \
  --verify-tag \
  --title "$TAG" \
  --notes-from-tag \
  "${RELEASE_FLAGS[@]}"

Published releases may be immutable. Never delete a published release to retrigger an integration: GitHub permanently reserves an immutable release's tag name, so the release cannot be recreated with that tag. Verify external integrations before publishing and create a new version if a release must be repeated.

Always use the exact tag, including the leading v, as the release title. Verify the published release. The tag-specific delivery lookup requires repository-webhook read access; if gh reports a missing admin:repo_hook scope, add it once with gh auth refresh -h github.com -s admin:repo_hook:

gh release view "$TAG" \
  --json url,tagName,name,isDraft,isPrerelease \
  --jq .
 
ZENODO_HOOK_ID="$(
  gh api repos/acgetchell/CDT-plusplus/hooks \
    --paginate \
    --jq '.[] | select(
      .active and
      (.events | index("release")) and
      (.config.url | startswith("https://zenodo.org/"))
    ) | .id'
)"
ZENODO_DELIVERY="$(
  gh api --paginate \
    "repos/acgetchell/CDT-plusplus/hooks/$ZENODO_HOOK_ID/deliveries" \
    --jq '.[] | select(.event == "release") | .id' |
    while IFS= read -r delivery_id; do
      gh api \
        "repos/acgetchell/CDT-plusplus/hooks/$ZENODO_HOOK_ID/deliveries/$delivery_id" |
        jq --arg tag "$TAG" 'select(
          .request.payload.release.tag_name == $tag
        ) | {event, action, status, status_code, delivered_at, redelivery}'
    done |
    jq -s 'sort_by(.delivered_at) | last'
)"
jq -e 'select(
  .status == "OK" and
  (.status_code >= 200 and .status_code < 400)
)' <<<"$ZENODO_DELIVERY"

For a release candidate intentionally deposited with Zenodo, verify the record and DOI without treating it as the final stable handoff. For the stable release, complete the Zenodo handoff prepared by issue #96 and executed by [issue #97]: confirm that Zenodo received the release, verify its version, date, title, authors, license, repository URL, and files, and retain the top-level CFF doi as the all-versions concept DOI.

Once Zenodo creates the stable record DOI, add it without replacing the concept DOI:

doi: "10.5281/zenodo.21487043"
identifiers:
  - type: doi
    value: "10.5281/zenodo.STABLE_RECORD_ID"
    description: "Zenodo DOI for version 1.0.0"

If the record DOI was unavailable before tagging, make this one focused post-release metadata commit, rerun just release-check and just docs-check, and do not rewrite the tag. Finish this update before the repository is made read-only.

Step 4: Clean up

After the release is verified, remove the release branch if the pull request did not already delete it:

git branch -d "release/$TAG"

git push origin --delete "release/$TAG"

If the remote branch was already deleted, the remote deletion command may be omitted.

Step 5: Stabilize, then complete the archival handoff

Issue #155 owns the stabilization gate and eventual irreversible final sequence. It remains blocked by issue #97 until the GitHub release, source archives, Zenodo record, DOI metadata, and repository description are verified:

enter a maintenance-only stabilization window in which changes are limited to release-blocking correctness, reproducibility, security, documentation, and metadata corrections;
retain #155 and any verified release blocker until the repository owner determines that the handoff has settled, no blockers remain, and CDT++ is no longer needed as a fallback for successor-integration risk;
publish any critical post-release correction as a new patch release rather than moving or replacing the v1.0.0 tag, then restart the relevant release verification;
close or disposition every remaining tracker, close #155 as the final repository mutation, and archive the GitHub repository; and
verify externally that the repository, release, documentation, and Zenodo links remain public and readable while issues and pull requests are read-only.

Do not close #155 or archive before the owner ends the stabilization window, retires the fallback hedge, and completes the version-specific DOI commit above. Do not leave a tracker open for work that cannot be performed after archival.

Release-critical fixes

If a critical problem is found before tagging, fix it through a pull request, regenerate CHANGELOG.md with just changelog-unreleased "$TAG" after the fix is merged, and rerun all validation steps. Defer non-critical fixes to the next version and document them in the changelog when appropriate.

If a problem is found after the tag is pushed or the GitHub release is published, do not retag the release. Correct it in a new release.