Skip to content

chore(release): diff pact.h and bump doc links in FFI release PRs - #1784

Merged
JP-Ellis merged 1 commit into
mainfrom
chore/ffi-release-header-diff
Nov 20, 2026
Merged

JP-Ellis merged 1 commit into
mainfrom
chore/ffi-release-header-diff

Conversation

@JP-Ellis

Copy link
Copy Markdown
Member

✈️ Pre-flight checklist

  • I have read the Contributing Guidelines on pull requests.
  • If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
  • If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

📝 Summary

scripts/release.py prepare ffi takes over two manual steps of every upstream FFI upgrade:

  1. pact.h diff in the PR body. The script downloads the header for the old and new upstream versions from their pact_ffi-v* GitHub releases. It appends a unified diff after the changelog in a collapsed <details> block. The reviewer sees at a glance whether the wrappers in pact_ffi/__init__.py need hand edits.
  2. Documentation link bump. The script rewrites the docs.rs/pact_ffi/X.Y.Z/ and pact-reference/blob/pact_ffi-vX.Y.Z/ links in pact_ffi/__init__.py. The release commit carries the file next to pyproject.toml and CHANGELOG.md.

Both steps run only when the upstream X.Y.Z changes. Wrapper-only bumps such as 0.5.12.0 → 0.5.12.1 skip them.

🔥 Motivation

Each FFI upgrade (e.g. dc6f966 for 0.5.12) repeated the same chores: diff the header by hand, then bump about 250 links. The diff now arrives with the release PR. The link bump needs no commit of its own.

Design choices:

  • Raw diff over a signature summary. A parsed list of added, removed and changed pactffi_* signatures would read faster. It would also need a C header parser, which is one more thing to break. The raw diff shows doc-comment changes too, and those often matter for wrapper docstrings.
  • Size cap. GitHub rejects PR bodies over 65,536 characters. The diff stops at a line boundary within the remaining budget and says how many lines it dropped.
  • Fence length. The header's doc comments can contain Markdown code fences, so the outer fence grows past the longest backtick run in the diff.
  • Link patterns match any version. Links that drifted behind get caught too. blob/master links and the 2024 blog post stay untouched.

Wrapper changes the diff calls for still land on main as their own commit. The release branch is force-pushed on every run.

🔨 Test Plan

scripts/release.py has no test suite. I verified by hand:

  • python scripts/release.py prepare ffi --dry-run against the live 0.5.12 → 0.5.13 bump. The rendered body contains the real header change, a doc comment on provider-state retries. All 245 docs.rs links and all 9 blob/pact_ffi-v links moved to 0.5.13.
  • render_header_diff with a 300-character budget prints the truncation note. Calling it with identical versions prints the no-change note.
  • ruff check, ruff format and the pre-push mypy hook pass.

🔗 Related issues/PRs

When the FFI release PR moves to a new upstream `pact_ffi` version, two
steps used to be manual: checking `pact.h` for changes the Python
wrappers must follow, and pointing the upstream documentation links in
`pact_ffi/__init__.py` at the new version.

`prepare ffi` now downloads `pact.h` for the old and new upstream
versions from their GitHub releases. It appends a unified diff to the
PR body in a collapsed block. The diff stops short of GitHub's PR body
size limit and says how many lines it left out. An unchanged header
gets a one-line note.

The same run rewrites the `docs.rs/pact_ffi/X.Y.Z/` and
`pact-reference/blob/pact_ffi-vX.Y.Z/` links to the new version and
commits `__init__.py` with the release files. The patterns match any
version, so links that drifted behind are caught too. Wrapper-only
bumps (`0.5.12.0` to `0.5.12.1`) skip both steps.

Wrapper changes the diff calls for still land on main as their own
commit. The release branch is force-pushed on every run.

Assisted-by: Claude Code:claude-opus-5-5
@codecov

codecov Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 66%. Comparing base (d27bc6a) to head (311c751).
⚠️ Report is 7 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files
@@         Coverage Diff          @@
##           main   #1784   +/-   ##
====================================
  Coverage    66%     66%           
====================================
  Files        23      23           
  Lines      3565    3565           
====================================
  Hits       2355    2355           
  Misses     1210    1210           
Flag Coverage Δ
examples 39% <ø> (ø)
tests 65% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

@JP-Ellis
JP-Ellis enabled auto-merge (rebase) November 20, 2026 01:16
@JP-Ellis
JP-Ellis merged commit 46fe5c3 into main Nov 20, 2026
38 checks passed
@JP-Ellis
JP-Ellis deleted the chore/ffi-release-header-diff branch November 20, 2026 01:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant