From 6c111afc341a045ebbc19078c12432f00541a658 Mon Sep 17 00:00:00 2001
From: JP-Ellis <josh@jpellis.me>
Date: Tue, 25 Nov 2025 14:26:32 +1100
Subject: [PATCH] docs: add consumer_version

Consumer version was recently added (in 3.2).

Signed-off-by: JP-Ellis <josh@jpellis.me>
---
 MIGRATION.md     |  5 ++++-
 docs/provider.md | 29 ++++++++++++++++++++++++++---
 2 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/MIGRATION.md b/MIGRATION.md
index 06ff1ea7b..f28020154 100644
--- a/MIGRATION.md
+++ b/MIGRATION.md
@@ -292,13 +292,16 @@ broker_builder = (
     )
     .include_pending()
     .provider_branch('main')
-    .consumer_tags('main', 'develop')
+    .consumer_version(branch='main')
+    .consumer_version(branch='develop')
     .build()
 )
 ```
 
 The `selector=True` argument returns a [`BrokerSelectorBuilder`][pact.verifier.BrokerSelectorBuilder] instance, which provides methods to configure which pacts to fetch. The `build()` call finalizes the configuration and returns the `Verifier` instance which can then be further configured.
 
+The `consumer_version` method provides fine-grained control over which consumer pacts are verified and can be called multiple times to add multiple selectors (combined with a logical OR). The older `consumer_versions` method is now deprecated in favor of `consumer_version`.
+
 ///
 
 #### Provider State Handling
diff --git a/docs/provider.md b/docs/provider.md
index 7edcd010a..576f201df 100644
--- a/docs/provider.md
+++ b/docs/provider.md
@@ -96,14 +96,38 @@ def test_provider_with_selectors():
         )
         .include_pending()  # Include pending pacts
         .include_wip_since("2023-01-01")  # Include WIP pacts since date
-        .provider_tags("main", "develop")
-        .consumer_tags("production", "main")
+        .provider_branch("main")
+        .consumer_version(branch="main")  # Specific consumer version selectors
+        .consumer_version(branch="develop")  # Can be called multiple times
         .build()  # Build the selector
     )
 
     verifier.verify()
 ```
 
+#### Consumer Version Selectors
+
+The `consumer_version` method provides fine-grained control over which consumer pacts are verified. It can be called multiple times to add multiple selectors, which are combined with a logical OR (pacts matching any selector will be included).
+
+Common use cases:
+
+```python
+# Verify pacts from a specific branch
+.consumer_version(branch="feature/new-api")
+
+# Verify pacts from deployed or released versions
+.consumer_version(deployed_or_released=True)
+
+# Verify pacts from main branch
+.consumer_version(main_branch=True)
+
+# Verify pacts from a specific consumer only
+.consumer_version(consumer="mobile-app", branch="main")
+
+# Verify pacts from a specific environment
+.consumer_version(deployed=True, environment="production")
+```
+
 More information on the selector options is available in the [API reference][pact.verifier.BrokerSelectorBuilder].
 
 ## Logging
@@ -139,7 +163,6 @@ if "CI" in os.environ:
     verifier.set_publish_options(  # (1)
         version="1.2.3",
         branch="main",
-        tags=["production"],
     )
 
 verifier.verify()