docs: update for v3 and add migration guide #1253

JP-Ellis · 2025-09-29T23:44:57Z

📝 Summary

Overhaul of the documentation in preparation of the V3 release.

In particular:

Add a migration guide
Update the consumer and provider docs with the new V3 interface
Update the matcher and generator module docs

🚨 Breaking Changes

The abstract Matcher and Generator classes have been renaned to AbstractMatcher and AbstractGenerator. This is not going to be a breaking change unless you have created your own matcher or generator.

🔥 Motivation

To help with the adoption of the soon-to-be-released version 3, for both new and existing Pact Python users.

🔨 Test Plan

🔗 Related issues/PRs

Resolves: Document migration to v3 of Pact Python #1222

Copilot

Pull Request Overview

This PR overhauds the documentation for the v3 release and implements a significant breaking change by renaming the abstract Matcher and Generator classes to AbstractMatcher and AbstractGenerator respectively.

Comprehensive migration guide added for v2 to v3 transition
Consumer and provider documentation rewritten with new v3 interface examples
Documentation improvements including expanded matching examples and generator usage

Reviewed Changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`src/pact/match/matcher.py`	Renames `Matcher` to `AbstractMatcher` and updates all type annotations and references
`src/pact/generate/generator.py`	Renames `Generator` to `AbstractGenerator` and updates docstrings
`src/pact/match/__init__.py`	Updates imports and adds comprehensive module documentation with examples
`src/pact/generate/__init__.py`	Updates imports and adds detailed generator documentation
`src/pact/interaction/_*.py`	Updates type annotations to use `AbstractMatcher`
`docs/consumer.md`	Complete rewrite with v3 API examples and modern patterns
`docs/provider.md`	Complete rewrite with new `Verifier` class usage
`MIGRATION.md`	New comprehensive migration guide for v2 to v3 transition
Other files	Minor documentation updates and configuration changes

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

src/pact/match/matcher.py

src/pact/generate/__init__.py

codecov · 2025-09-29T23:49:36Z

Codecov Report

❌ Patch coverage is 63.63636% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 52%. Comparing base (62b8903) to head (b64a4c4).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/pact/verifier.py	21%	11 Missing ⚠️
src/pact/match/matcher.py	68%	6 Missing ⚠️
src/pact/match/__init__.py	71%	2 Missing ⚠️
src/pact/interaction/_http_interaction.py	66%	1 Missing ⚠️

Additional details and impacted files

@@         Coverage Diff          @@
##           main   #1253   +/-   ##
====================================
- Coverage    52%     52%   -1%     
====================================
  Files        32      32           
  Lines      3730    3740   +10     
====================================
  Hits       1967    1967           
- Misses     1763    1773   +10

Flag	Coverage Δ
tests	`52% <63%> (-1%)`	⬇️

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

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

MIGRATION.md

YOU54F · 2025-10-01T12:50:22Z

MIGRATION.md

+
+<!-- markdownlint-disable code-block-style -->
+
+=== "Local Files"


can this be a url , for verifications by webhook?

how do we add auth in that case?

this is the last clarification I really want to mop up before we box this off. If we don't have this functionality, then we can just ticket it up and work forward. If the func does exist, it would be great to document, as to reach pact nirvana, you have two provider verification flows, one by url (triggered by webhook) and one by querying the pact broker with selectors which returns dynamic results.

This was a distinct gap in V2

#332

Good shout Yousaf, we can close that off with this release too!

I have no tested the webhook flow at all... so I'll take a look and see.

MIGRATION.md

YOU54F

added comment about msg pact, forgot to submit review as had to go into few meetings

docs/consumer.md

MIGRATION.md

JP-Ellis · 2025-10-01T22:13:28Z

Thanks @YOU54F for the thorough feedback!

I've incorporated your changes and have updated the migration guide.

As for the message-related docs, I want to address that in a separate PR as that is entirely new for V3.

MIGRATION.md

mefellows

I only have a few comments to review, it's a great guide (and we can always continue to improve it once people start taking it for a spin).

MIGRATION.md

mefellows · 2025-10-02T11:11:17Z

MIGRATION.md

+
+<!-- markdownlint-disable code-block-style -->
+
+=== "Local Files"


Good shout Yousaf, we can close that off with this release too!

MIGRATION.md

docs/consumer.md

docs/provider.md

YOU54F

last round of comments, nothing too big

docs/consumer.md

YOU54F · 2025-10-02T16:45:35Z

docs/consumer.md

+    /path/to/pacts/consumer-provider.json \
+    --consumer-app-version 1.0.0 \
+    --tag-with-git-branch \
+    --auto-detect-version-properties


lets avoid tags if we can, and remove the consumer-app-version, as its preferred there is at least a sha identifier as part of the version, which auto-detect-version-properties will pick up

So remove the --tag-with-git-branch option?

Update: I've removed it from the latest update to this PR.

thank you, I'd like to remove consumer-app-version if possible too, or maybe update to be the <python project version>-<git sha> if you want to retain it.

docs/provider.md

JP-Ellis · 2025-10-03T02:19:44Z

I've pushed the latest changes:

A few typos/minor wording changes here and there
Update the broker_source to use env vars
Clarified some docs on the selector option

I do need to check the given implementation to make sure that new provider states get created, as opposed to merely merging them.

UPDATE: last commit should clarify this.

Make clear it is abstract by naming it `AbstractMatcher`. BREAKING CHANGE: The abstract `pact.match.Matcher` class has been renamed to `pact.match.AbstractMatcher`. Signed-off-by: JP-Ellis <[email protected]>

Signed-off-by: JP-Ellis <[email protected]>

Make clear it is abstract by naming it `AbstractGenerator`. BREAKING CHANGE: The abstract `pact.generate.Generator` class has been renamed to `pact.generate.AbstractGenerator`. Signed-off-by: JP-Ellis <[email protected]>

Signed-off-by: JP-Ellis <[email protected]>

Allows the broker source information to be populated from environment variables. This still requires the `broker_source` method to be called: ```python ( Verifier("my-provider") # ... .broker_source() ) ``` This can be disabled by setting the new `use_env` argument to `False` (defaults to True), or by setting the relevant argument to `None` if you want to disable an input. Signed-off-by: JP-Ellis <[email protected]>

Signed-off-by: JP-Ellis <[email protected]>

YOU54F

Looking great now, and we can add a full messages docs in a follow up PR and also look at the webhook flow (pact by url). it isn't something present in v2, so doesn't really need consideration for migration, but definitely helps us be more pact nirvana compliant :)

Great stuff Josh

JP-Ellis self-assigned this Sep 29, 2025

Copilot AI review requested due to automatic review settings September 29, 2025 23:44

Copilot AI reviewed Sep 29, 2025

View reviewed changes

src/pact/match/matcher.py Show resolved Hide resolved

src/pact/generate/__init__.py Outdated Show resolved Hide resolved

src/pact/generate/__init__.py Outdated Show resolved Hide resolved

JP-Ellis force-pushed the docs/v3-overhaul branch from 474f3c6 to 24f8bfd Compare September 29, 2025 23:46

JP-Ellis force-pushed the docs/v3-overhaul branch 2 times, most recently from ceeef32 to 7ee79f6 Compare October 1, 2025 05:47