Hey team!:wave: <@UELMFD9PG> and I were talking ab...
# documentation
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-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)
💛 2
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
👋 1
Hey @Rafael Anachoreta just as a heads up, I have a fairly packed week with a few things on for review, but want to definitely pick up this thread near the tail end, or next week. If you wanted to propose any changes in the mean-time, I can take the time out to support them otherwise I will be in touch shortly. If anyone reading wants to get involved, then please reach out. The content on our site becomes alive when it's expertly curated by our community so I am loving all the attention folks are giving it.
👍 2
@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.
🙇 1
We're hoping to knock off the final clients in the next month or so.
As you can imagine, trying to schedule OSS work can be difficult.
I really appreciate the list of places to update - that will help a lot.
I'm going to copy the list into an issue so we address them all.
If you're interested in contributing, I'd be very happy to accept PRs.
The question is - do we wait for all the clients to be updated and go straight to just documenting branches and envs, or do we update it now and have both the tag and branch/env docs side by side.
Having a few chats with Yousaf, I think he's making a few lists and lists of lists :)
Deprecating sections of docs is hard for sure 😮
it's tricky, because I know there will be users stuck on versions of the broker/clients that can only use tags for years.
it's often hard for devs to be able to justify the time in upgrading libraries.
💯 1
"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 🥲
🤔 would making old (deprecated) docs more polished be of value to help guide "but what about this" in the new approach?
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)
I love the fact everyone is loving wanting to make the docs better. You guys/girls 😊
Yup. Definitely need a clear table to show what versions are necessary.
It's too spread out at the moment.
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! ❤️