ci: PR-based, per-crate releases

[JP-Ellis]

Important

This PR stacks on #564. Two commits must be dropped before merge:

• ci: TEMPORARY build release artifacts on the release-process PR
• ci: TEMPORARY gate pact_ffi on the release-process PR

Together they let this PR run the full pact_ffi release build, so its artifacts can be checked before anything is tagged.

Goal

Replace the per-crate release.groovy scripts, run locally by named people, with a PR-based flow:

1. Each crate has its own draft release PR, kept up to date from master.
2. Merging a release PR tags the merge commit.
3. The tag builds, publishes to crates.io through trusted publishing, and creates the GitHub release.

Crates release independently. Downstream FFI installers keep their URLs and asset names until 2027-06-30.

How it works

• Release PRs. release-pr.yml runs on every push to master.
  • prepare runs release-plz update -p <crate> for each crate and keeps a draft release/<crate> PR.
  • Once a person pushes to a release PR, the bot stops regenerating it.
• Tags. The tag job runs tag-releases.sh, which tags each crate whose version has no tag.
  • It tags the commit that set the version, which is the release PR's merge.
  • It pushes one tag per push, with the bot App's token, so the release workflow starts.
• Release workflow. release.yml is generated by dist, with five marked hand edits. For pact_ffi and pact_verifier_cli it runs:
  1. build all eight targets
  2. publish to crates.io (publish-crate.yml)
  3. create the GitHub release
  4. republish legacy asset names (legacy-artifacts.yml)
  5. push the pact-verifier image (publish-containers.yml)
• Library crates. Tags for the four library-only crates go through release-crate.yml: publish, then a GitHub release.
• Release gate. Marking a pact_ffi or pact_verifier_cli release PR ready runs the same eight-target build, without publishing.
• Checks on release PRs.
  • release-deps names any sibling crate that must be released first.
  • On ready PRs, cargo package builds the crate against its released siblings.

RELEASING.md describes the flow for maintainers.

Artifacts

• Linux builds run in containers so the libraries keep their linkage.
  • gnu builds in manylinux_2_28, a glibc 2.28 floor. That is the oldest glibc among supported major distributions: the RHEL 8 family has 2.28, RHEL 9 and Amazon Linux 2023 2.34, Ubuntu 22.04 2.35, Debian 12 2.36. 0.5.11 needed 2.18; the distributions between 2.18 and 2.28 are all out of support.
  • musl builds in cross-rs's musl images on x64 runners. That keeps pact_ffi's .so linked against musl, and the CLI static.
• check-linkage.sh checks every Linux library and the CLI before the legacy names are published.
• Windows.
  • Both Windows targets build with MSVC on Windows runners, and link the runtime dynamically, as before.
  • dist's archives omit the import library pact_ffi.dll.lib. import-lib.sh rebuilds it from the DLL's export table. Against the 0.5.11 DLLs, the rebuilt libraries define the same symbols as rustc's.
• Legacy names. They are checked against the asset lists of libpact_ffi-v0.5.11 and pact_verifier_cli-v1.3.5. For pact_ffi they go to a libpact_ffi-v<version> release, which never becomes "latest".
• Docker. The image is one multi-platform manifest, tagged <version> and latest. The per-architecture tags <version>-amd64 and <version>-arm64v8 are no longer pushed.

Commit sequence

1. chore: reset crate versions to their last releases: each version equals its last tag, so the first run tags nothing.
2. build: patch pact_matching by path alone: a version requirement in [patch] breaks cargo update once release PRs bump the crate.
3. build: configure release-plz for per-crate releases: registry mode, the changelog template, changelog-section.sh, and the new tools in mise.toml.
4. ci: block release PRs that need an unreleased workspace crate
5. ci: maintain one draft release PR per crate and tag merged releases
6. ci: publish crates through crates.io trusted publishing
7. ci: build releases with dist
8. ci: republish pre-dist asset names during a transition period
9. ci: publish the pact-verifier image after each CLI release
10. ci: release library-only crates from their tags
11. chore: remove manual release tooling: the groovy and shell release scripts, Cross.toml, and the Conan recipes. The Conan remote is deactivated, and the recipe has not moved past 0.0.4 since 2021.
12. fix(ci): tag the commit that set each released version
13. fix(ci): guard tagging and release PRs against crates.io state
14. fix(ci): build Linux releases in containers to keep their linkage
15. fix(ci): give each musl crate its own CRT linkage, drop manual release-pr runs
16. ci: TEMPORARY build release artifacts on the release-process PR: drop before merge.
17. feat(ci): check release gate artifacts locally with legacy-artifacts.sh
18. docs: describe checking a release gate build before merge
19. fix(ci): plan a release gate build for the release PR's own tag: without a tag, dist plans both dist crates together and refuses their unrelated versions. This PR's first build caught it.
20. ci: TEMPORARY gate pact_ffi on the release-process PR: drop before merge.
21. fix(ci): install xz in the musl build containers: dist's installer needs xz, and the cross-rs images lack it.
22. fix(ci): run the header build from pact_ffi's directory: dist runs extra-artifact builds from the package directory.

Alternatives weighed

• release-plz git_only mode. It opens the git repository at the Cargo workspace directory without searching parent directories, so it fails with the workspace in rust/. Registry mode works from rust/. refactor: move the Cargo workspace to the repository root #565 proposes moving the workspace to the root, separately.
• release-plz release for tagging. In registry mode it would decide by crates.io, which lags the tag by a full release build. tag-releases.sh decides by tags.
• Building musl on Ubuntu or in Alpine.
  • On Ubuntu, a musl cdylib links glibc's libc.so.6.
  • On arm64 runners, GitHub has no Alpine Node for JavaScript actions.
• dist's default cargo-xwin for aarch64 Windows. It cross-compiles on Linux, unlike every release so far.

Before merge

• Driver release. fix(driver): move to zip 9, since every zip 8 release is yanked pact-plugins#118 must be released. cargo-semver-checks resolves pact-plugin-driver from crates.io, and every 1.2.x release requires zip 8.x, which is all yanked.
• Full artifact check. Done on run 38863282720: all eight targets and the headers built; the legacy names match; gnu tops out at GLIBC_2.28; musl needs musl's libc.so and libgcc_s.so.1, like 0.5.11; every build used rustc 1.99.1. The temporary commits run the pact_ffi release build on this PR, draft or not. Run the artifact check on that run with tag pact_ffi-v0.5.11. pact_verifier_cli is first built by its own release PR's gate.
• Drop both temporary commits, and rebase onto master after ci: consolidate and speed up CI #564 merges.

Maintainer setup

• crates.io trusted publishers. For each of the six crates, add one with repository pact-foundation/pact-reference and environment crates-io.

  • Workflow release.yml for pact_ffi and pact_verifier_cli.
  • Workflow release-crate.yml for pact_models, pact_matching, pact_consumer and pact_verifier.

• crates-io environment. Create it.

• Bot App. Install PACT_FOUNDATION_BOT on this repository, with contents and pull-request write access.

• Branch protection. Allow the bot to push release/* branches and tags. Require CI complete.

• Container registries.

  • Make DOCKER_HUB_USERNAME and DOCKER_HUB_TOKEN available to this repository.
  • Give the repository write access to the ghcr.io/pact-foundation/pact-verifier package.

• Migration tags. Push them before merging:

  git fetch --tags origin
  git tag pact_models-v1.3.16 'libpact_models-v1.3.16^{}'
  git tag pact_matching-v2.0.11 'libpact_matching-v2.0.11^{}'
  git tag pact_ffi-v0.5.11 'libpact_ffi-v0.5.11^{}'
  git push origin pact_models-v1.3.16 pact_matching-v2.0.11 pact_ffi-v0.5.11

  Without them, the first tag run would find these versions untagged. tag-releases.sh refuses to tag a version already on crates.io, but the tags are needed for release-deps and the changelog links.

First release: pact_ffi, live

The first release is the rehearsal, so check each step before taking the next.

1. Merge this PR.
   • Watch the Release PR workflow on master.
   • tag creates no tags.
   • prepare opens draft release/<crate> PRs for crates with changes.
2. Review release/pact_ffi.
   • Check the version and the changelog section; edit the branch if needed.
   • Mark it ready. test.yml runs, including release-deps and cargo package, and so does the eight-target release gate.
3. Check the gate's artifacts with the artifact check, using the new version's tag name.
4. Merge release/pact_ffi.
   • The tag job pushes pact_ffi-v<version>.
   • The release workflow runs plan, build, host, publish, announce and the legacy artifacts.
5. Verify.

   • crates.io lists pact_ffi <version>.

   • Release pact_ffi-v<version> has eight archives, with .sha256 files, plus pact.h and pact-cpp.h.

   • Release libpact_ffi-v<version> is not marked latest, and its assets match the expected list:

     diff .github/scripts/tests/legacy-expected-ffi.txt \
          <(gh release view "libpact_ffi-v<version>" --json assets --jq '.assets[].name' | sort)

   • A downstream installer can fetch the new version. pact-python and pact-js build releases/download/libpact_ffi-v<version>/<name>.

If a step fails

Failure	State	Recovery
Build	Tag only; nothing published	Transient: re-run the failed jobs. Code fix: release the next patch through a new release PR.
Publish	Tag and build; no crates.io version, no GitHub release	Fix the cause, e.g. the trusted publisher config, then re-run the failed jobs.
Announce	Published to crates.io; no GitHub release	Re-run the failed jobs. Publish skips a version already on crates.io.
Legacy artifacts	GitHub release done; legacy names missing	Fix, then run the Legacy artifacts workflow manually with the tag. A linkage failure here means the release's own archives are mislinked too.
tag job	Release PR merged, no tag	Re-run it, or push any commit to master. The script tags the release merge commit either way.

Re-run failed jobs only. A full re-run of the release workflow fails at release creation once the release exists.

Checking a release build's artifacts

This runs against a release gate run, or this PR's own run while the temporary commit is in place. It needs gh, LLVM (llvm-dlltool, llvm-readobj) and readelf. On macOS, use Homebrew's llvm.

run=<release workflow run id>
gh run download "$run" -R pact-foundation/pact-reference -p 'artifacts-*' -D gate
mkdir -p gate-flat
find gate -type f \( -name '*.tar.xz' -o -name '*.zip' -o -name 'pact*.h' \) -exec cp {} gate-flat/ \;

LEGACY_ARCHIVES=gate-flat .github/scripts/legacy-artifacts.sh pact_ffi-v<version> out-ffi
diff .github/scripts/tests/legacy-expected-ffi.txt <(ls out-ffi | sort)

LEGACY_ARCHIVES=gate-flat .github/scripts/legacy-artifacts.sh pact_verifier_cli-v<version> out-cli
diff .github/scripts/tests/legacy-expected-cli.txt <(ls out-cli | sort)

gh run view "$run" -R pact-foundation/pact-reference --log | grep -c 'rustc 1.99.1'

legacy-artifacts.sh fails if any of these is wrong:

• a musl library doesn't link musl
• the CLI isn't static
• a gnu artifact needs a glibc newer than 2.28
• a Windows import library can't be rebuilt

The two diffs print nothing when the asset names match. Every build job's log should show rustc 1.99.1, because 1.99.0 miscompiled C bool returns.