Hey team!👋 @Yousaf Nabi (pactflow.io) and I were talking about some potential improvement opportunities for the new branch + record deployments approach in favor of tags, and I was sharing how I feel like the documentation hasn’t properly reflected the best practices throughout its various pages. Some examples: • Does “latest” pacts apply to branches too? Assuming you only have branches and no tags, will it work? This isn’t clear and isn’t reflected in the branches documentation https://docs.pact.io/pact_broker/tags#latest-pacts and https://docs.pact.io/pact_broker/tags#when-retrieving-pacts-to-verify • There is no way to identify versions by environment using the new record-deployment approach https://docs.pact.io/pact_broker/tags#identifying-versions-by-tag and https://pact.canny.io/feature-requests/p/support-environmentreleases-on-describe-version • This mention of environments and can-i-deploy is outdated in the context of the new

record-deployment

/`record-releases` https://docs.pact.io/pact_broker/tags#before-deploying-to-an-environment • This section is outdated: https://docs.pact.io/pact_broker/branches#support (I think this is a known problem and a hard one to circumvent, so it’s ok) • The recommended configuration for providers is outdated https://docs.pact.io/provider/recommended_configuration#verification-triggered-by-provider-change • The recommended configuration for consumers is outdated https://docs.pact.io/consumer/recommended_configuration Overall, my proposal involves mostly migrating all the information we have on https://docs.pact.io/pact_broker/tags to https://docs.pact.io/pact_broker/branches, and updating it where applicable. Relevant PR and discussion: https://github.com/pact-foundation/docs.pact.io/pull/103 CC: @Beth (pactflow.io/Pact Broker/pact-ruby)

Love the effort @Rafael Anachoreta, this is a really beneficial endeavour to get the spotlight on areas which need some love and hopefully we can do something collaborative. @Mike Geeves started collecting some discussion around where best to track these kind of pieces of work, and potential areas of focus, so this leads neatly into it, but there is still some loose ends around how best to gather these thoughts into actionable items and a roadmap, so people can easily contribute. https://pact-foundation.slack.com/archives/CAN147DFD/p1638947223038000 The google season of docs proposals and case studies from last year have given me loads of food for thought https://developers.google.com/season-of-docs/docs/2021/participants I found redoclys one particularly resonated with our challenges

@Rafael Anachoreta thanks for the feedback. You're absolutely right, the docs are out of date. The problem has been that not all the clients support branches and environments yet, so I haven't been able to do a full update of best practice recommendations.

Having a few chats with Yousaf, I think he's making a few lists and lists of lists :)

it's tricky, because I know there will be users stuck on versions of the broker/clients that can only use tags for years.

"how will I know it worked" -> "everything you can see will look exactly the same unless it doesn't" were some of the hardest arguments 🥲

If we are • clear about the libraries that don't support it on a feature matrix perhaps https://docs.pact.io/roadmap/feature_support • We can then provide a path for request it pact.canny.io and show it on a roadmap that way I think it's fine to show that this way is new, recommend, caveat not everyone supports it and this is the old way that everything supports (if indeed it does)

Yup. Definitely need a clear table to show what versions are necessary.

I’ll have a look at all the PRs later today to see how/if I can contribute. Thank you all for so promptly jumping into this and moving the discussion! ❤️