Harden release artifacts and process ahead of a public release

[sqt]

Motivation

We're targeting a public zzdds release soon so rmw_zzdds can pin it. The release pipeline had gaps that a downstream C/C++ consumer would hit first:

• package-libs builds prebuilt bundles but only checks the tree it just built, in place — nothing verifies a consumer can find_package(ZZDDS) / pkg-config a bundle after it's been extracted somewhere else (the exact path rmw_zzdds and any CMake consumer take).
• -Dtarget was never actually cross-compiled anywhere in CI — every lane built the native glibc triple, so musl / static-binary consumers were untested.
• Release notes were raw git log subjects rather than the curated CHANGELOG.md.
• The Version: field in the installed zzdds.pc / zzdds-config.cmake came from a hand-maintained string in build.zig that had drifted two minors behind build.zig.zon.
• For a repo about to go public with prebuilt bundles, there was no written statement of the API/ABI stability posture.

Description of changes

• Prebuilt-bundle consume check. New scripts/verify_release_bundle.py + fixtures under test/release-bundle/. release.yml's package-libs now extracts the finished per-platform tarball into an unrelated directory and drives a real downstream consume: structural completeness, pkg-config / CMake-package relocatability (no baked-in build paths), the bundled bin/zidl runs, and find_package(ZZDDS) + pkg-config build examples/{c,cpp}/hello_world and a minimal consumer against the relocated prefix — Linux also runs the hello_world pub/sub pair. Linux = full, macOS = --skip-example-run (skips only the live-UDP pair), Windows = --configure-only.
• musl / static Linux target lane. zig build test -Dtarget=x86_64-linux-musl added to run_deterministic_matrix.py (so ci.yml's test-linux covers it) and release.yml's test job (Linux x86_64). The static musl binary runs natively on the glibc runner, so it's full-suite execution coverage (1076/1076), not just a build check.
• Release notes from CHANGELOG.md. New scripts/extract_changelog.py; release.yml's publish job builds the GitHub-release body from the curated date-headed CHANGELOG.md sections since the previous tag (matched by the tag's own date), falls back to commit subjects only if that yields nothing, and always appends a compare link.
• Version single-sourced. build.zig now reads @import("build.zig.zon").version instead of a separate hardcoded string, so zzdds.pc / zzdds-config.cmake track the package version release.yml bumps at tag time.
• Stability posture recorded. New "Versioning / Releases" section in docs/decisions.md: pre-1.0, any release may break source/ABI compatibility; consumers pin an exact vX.Y.Z-zig.A.B.C tag or bundle; downstream middleware owns its own version mapping. release.yml release notes carry a matching "Stability" section; docs/roadmap.md's --runtime-version entry updated to match.
• CHANGELOG.md / docs/roadmap.md updated for all of the above.

[greptile-apps]

Greptile Summary

The PR hardens release preparation by validating relocated C/C++ bundles, adding x86_64 musl coverage, sourcing release notes from the curated changelog, and deriving installed package metadata from the package version.

• Exercises extracted Linux and macOS bundles through CMake, pkg-config, the bundled generator, and sample consumers.
• Adds host-gated musl testing to the deterministic matrix and release workflow.
• Documents the pre-1.0 stability policy and release-consumer expectations.
• Uses complete changelog sections while intentionally falling back to commit subjects for same-day releases.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
.github/workflows/release.yml	Adds musl execution, relocated-bundle verification on supported hosts, curated release-note generation, and documented Windows verification limits.
scripts/verify_release_bundle.py	Validates extracted bundle structure, relocatability, generator execution, downstream CMake/pkg-config consumption, and supported runtime examples.
scripts/run_deterministic_matrix.py	Adds the musl test only on x86_64 Linux hosts and handles intentional host-based omission.
scripts/extract_changelog.py	Extracts complete new changelog sections without fragmenting multiline entries and signals fallback when no new heading exists.
build.zig	Derives installed package metadata from build.zig.zon to prevent version drift.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Build install tree] --> B[Create platform tarball]
  B --> C[Extract into unrelated prefix]
  C --> D[Check structure and relocatability]
  D --> E[CMake and pkg-config consumers]
  E --> F[Run supported examples]
  F --> G[Upload release bundle]
  H[CHANGELOG sections] --> I[Generate release body]
  I --> J[Publish release with bundles]

Loading

_{Reviews (3): Last reviewed commit: "resolving CI issues" | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!