docs: pending and WIP pacts

pact-foundation · Apr 9, 2020 · a53da07 · a53da07
1 parent d5b4279
commit a53da07
Showing 1 changed file with 65 additions and 49 deletions.
diff --git a/README.md b/README.md
@@ -37,55 +37,57 @@ Read [Getting started with Pact] for more information for beginners.
 <!-- TOC -->
 
 - [Pact Go](#pact-go)
-    - [Introduction](#introduction)
-    - [Table of Contents](#table-of-contents)
-    - [Versions](#versions)
-    - [Installation](#installation)
-        - [Go get](#go-get)
-        - [Installation on \*nix](#installation-on-\nix)
-    - [Using Pact](#using-pact)
-    - [HTTP API Testing](#http-api-testing)
-        - [Consumer Side Testing](#consumer-side-testing)
-        - [Provider API Testing](#provider-api-testing)
-            - [Provider Verification](#provider-verification)
-            - [Provider States](#provider-states)
-            - [Before and After Hooks](#before-and-after-hooks)
-            - [Request Filtering](#request-filtering)
-                - [Example: API with Authorization](#example-api-with-authorization)
-            - [Lifecycle of a provider verification](#lifecycle-of-a-provider-verification)
-        - [Publishing pacts to a Pact Broker and Tagging Pacts](#publishing-pacts-to-a-pact-broker-and-tagging-pacts)
-            - [Publishing from Go code](#publishing-from-go-code)
-            - [Publishing Provider Verification Results to a Pact Broker](#publishing-provider-verification-results-to-a-pact-broker)
-            - [Publishing from the CLI](#publishing-from-the-cli)
-            - [Using the Pact Broker with Basic authentication](#using-the-pact-broker-with-basic-authentication)
-            - [Using the Pact Broker with Bearer Token authentication](#using-the-pact-broker-with-bearer-token-authentication)
-    - [Asynchronous API Testing](#asynchronous-api-testing)
-        - [Consumer](#consumer)
-        - [Provider (Producer)](#provider-producer)
-        - [Pact Broker Integration](#pact-broker-integration)
-    - [Matching](#matching)
-        - [Matching on types](#matching-on-types)
-        - [Matching on arrays](#matching-on-arrays)
-        - [Matching by regular expression](#matching-by-regular-expression)
-        - [Match common formats](#match-common-formats)
-            - [Auto-generate matchers from struct tags](#auto-generate-matchers-from-struct-tags)
-    - [Tutorial (60 minutes)](#tutorial-60-minutes)
-    - [Examples](#examples)
-        - [HTTP APIs](#http-apis)
-        - [Asynchronous APIs](#asynchronous-apis)
-        - [Integrated examples](#integrated-examples)
-    - [Troubleshooting](#troubleshooting)
-            - [Splitting tests across multiple files](#splitting-tests-across-multiple-files)
-            - [Output Logging](#output-logging)
-            - [Check if the CLI tools are up to date](#check-if-the-cli-tools-are-up-to-date)
-            - [Disable CLI checks to speed up tests](#disable-cli-checks-to-speed-up-tests)
-            - [Re-run a specific provider verification test](#re-run-a-specific-provider-verification-test)
-        - [Verifying APIs with a self-signed certificate](#verifying-apis-with-a-self-signed-certificate)
-        - [Testing AWS API Gateway APIs](#testing-aws-api-gateway-apis)
-    - [Contact](#contact)
-    - [Documentation](#documentation)
-    - [Roadmap](#roadmap)
-    - [Contributing](#contributing)
+  - [Introduction](#introduction)
+  - [Table of Contents](#table-of-contents)
+  - [Versions](#versions)
+  - [Installation](#installation)
+    - [Go get](#go-get)
+    - [Installation on \*nix](#installation-on-\nix)
+  - [Using Pact](#using-pact)
+  - [HTTP API Testing](#http-api-testing)
+    - [Consumer Side Testing](#consumer-side-testing)
+    - [Provider API Testing](#provider-api-testing)
+      - [Provider Verification](#provider-verification)
+      - [Provider States](#provider-states)
+      - [Before and After Hooks](#before-and-after-hooks)
+      - [Request Filtering](#request-filtering)
+        - [Example: API with Authorization](#example-api-with-authorization)
+      - [Pending Pacts](#pending-pacts)
+      - [WIP Pacts](#wip-pacts)
+      - [Lifecycle of a provider verification](#lifecycle-of-a-provider-verification)
+    - [Publishing pacts to a Pact Broker and Tagging Pacts](#publishing-pacts-to-a-pact-broker-and-tagging-pacts)
+      - [Publishing from Go code](#publishing-from-go-code)
+      - [Publishing Provider Verification Results to a Pact Broker](#publishing-provider-verification-results-to-a-pact-broker)
+      - [Publishing from the CLI](#publishing-from-the-cli)
+      - [Using the Pact Broker with Basic authentication](#using-the-pact-broker-with-basic-authentication)
+      - [Using the Pact Broker with Bearer Token authentication](#using-the-pact-broker-with-bearer-token-authentication)
+  - [Asynchronous API Testing](#asynchronous-api-testing)
+    - [Consumer](#consumer)
+    - [Provider (Producer)](#provider-producer)
+    - [Pact Broker Integration](#pact-broker-integration)
+  - [Matching](#matching)
+    - [Matching on types](#matching-on-types)
+    - [Matching on arrays](#matching-on-arrays)
+    - [Matching by regular expression](#matching-by-regular-expression)
+    - [Match common formats](#match-common-formats)
+      - [Auto-generate matchers from struct tags](#auto-generate-matchers-from-struct-tags)
+  - [Tutorial (60 minutes)](#tutorial-60-minutes)
+  - [Examples](#examples)
+    - [HTTP APIs](#http-apis)
+    - [Asynchronous APIs](#asynchronous-apis)
+    - [Integrated examples](#integrated-examples)
+  - [Troubleshooting](#troubleshooting)
+      - [Splitting tests across multiple files](#splitting-tests-across-multiple-files)
+      - [Output Logging](#output-logging)
+      - [Check if the CLI tools are up to date](#check-if-the-cli-tools-are-up-to-date)
+      - [Disable CLI checks to speed up tests](#disable-cli-checks-to-speed-up-tests)
+      - [Re-run a specific provider verification test](#re-run-a-specific-provider-verification-test)
+    - [Verifying APIs with a self-signed certificate](#verifying-apis-with-a-self-signed-certificate)
+    - [Testing AWS API Gateway APIs](#testing-aws-api-gateway-apis)
+  - [Contact](#contact)
+  - [Documentation](#documentation)
+  - [Roadmap](#roadmap)
+  - [Contributing](#contributing)
 
 <!-- /TOC -->
 ## Versions
@@ -430,6 +432,20 @@ for different test cases:
 
 _Important Note_: You should only use this feature for things that can not be persisted in the pact file. By modifying the request, you are potentially modifying the contract from the consumer tests!
 
+#### Pending Pacts
+
+Pending pacts is a feature that allows consumers to publish new contracts or changes to existing contracts without breaking Provider's builds. It does so by flagging the contract as "unverified" in the Pact Broker the first time a contract is published. A Provider can then enable a behaviour (via `EnablePending: true`) that will still perform a verification (and thus share the results back to the broker) but _not_ fail the verification step itself.
+
+This enables safe introduction of new contracts into the system, without breaking Provider builds, whilst still providing feedback to Consumers as per before.
+
+See the [docs](https://docs.pact.io/pending) and this [article](http://blog.pact.io/2020/02/24/how-we-have-fixed-the-biggest-problem-with-the-pact-workflow/) for more background.
+
+#### WIP Pacts
+
+WIP Pacts builds upon pending pacts, enabling provider tests to pull in _any_ contracts applicable to the provider regardless of the `tag` it was given. This is useful, because often times consumers won't follow the exact same tagging convention and so their workflow would be interrupted. This feature enables any pacts determined to be "work in progress" to be verified by the Provider, without causing a build failure.
+
+See the [docs](https://docs.pact.io/wip) and this [article](http://blog.pact.io/2020/02/24/introducing-wip-pacts/) for more background.
+
 #### Lifecycle of a provider verification
 
 For each _interaction_ in a pact file, the order of execution is as follows: