Improve documentation for Pending and Work In Progress Pacts

[pendsley]

After integrating pending/wip pact support into our workflow, and answering various questions in Slack, I have compiled a list of suggestions that may (hopefully) help prevent questions in the future

Pending pacts

• Add a section/note about the use case this solves
  • Changes to the consumer can't break a provider's build

Work In Progress pacts

• Add a section/note about the use case this solves
  • Makes it easier to merge feature branches for providers/consumers AFTER the feature is implemented/verified with feature branches.
• Migrate/copy the information from the blog post to the official docs.
  • It feels a little clunky that the "how it works" part is not in the official docs
  • It's slightly jarring to have to read a blog post for the feature announcement to find out how it works
  • Having the info in the official docs makes it easier and more accessible to update/maintain
• Add documentation stating that if a provider's tag does not exist in the broker before verification is ran, no WIP pacts will be included in verification
  • This has come up a few times in Slack, and always seems to catch people off guard
  • Consider adding the reason why we do this?
    • If /for-verification returned WIP pacts when the providerVersionTags does not exist in broker, that means all your existing pacts (since includeWipPactsSince) will be verified against new feature branches. Which is probably something most people don't want most of the time? Really, you probably only care about the one consumer feature branch you're implementing functionality for. On the other hand, it seems like people expect it to return WIP pacts if the tag doesn't exist yet. But this is kind of strange for feature development if you think about it, because after the first successful verification, it won't pick it up anymore (because it's no longer WIP)

Other

• Update the CI/CD Workshop to better demonstrate how WIP pacts work, and what problem they solve
  • Create provider feature branch. Show failed verification and failed build with no changes
  • Implement changes on feature branch, show successful verification for feature branch.
  • Switch to main branch, and show failed verification with successful build
  • Merge feature branch, and show successful verification
  • Re-run and show the WIP pact is not included

[bethesque]

Awesome stuff. I'll make sure I tick all these off.

[danilchican]

When it will be done?:)

[bethesque]

The links to the docs are below, but I need to go back and make sure I've covered everything Phil raised here. Thanks for the reminder.

https://docs.pact.io/pact_broker/advanced_topics/pending_pacts/ https://docs.pact.io/pact_broker/advanced_topics/wip_pacts/

[bethesque]

Copying @pendsley's excellent description here for later use.

If the pacts are still recorded as not verified in the broker, then neither the provider nor consumer can deploy if they check the broker.

Kind of, but it's a little more nuanced. The consumer cannot deploy the version that has not been verified. The provider can still deploy non-breaking changes with the existing consumers. It cannot deploy any version that breaks a contract with the currently deployed consumers

All this does is allow the provider to get through the verification step without a failure.

Correct. Without pending pacts, a consumer could effectively block a provider's workflow by publishing a contract that is not supported by the provider. If this contract is merged into the main development branch, and providers verify against that tag, the provider's build will be broken until the issue is resolved. By using pending pacts, the provider team can continue to work on non-breaking changes with contracts it has already verified. Using pending pacts will let the provider team shift priorities to a hotfix that needs to go out now. Otherwise, they would have to resolve the contract compatibility issue first.