Docs Enhancement - Visible version tags for docs that provide code examples

[toriancrane]

Description

Dependency on #674

In reviewing issues across the repos, I have seen a few issues come up as a result of the code examples provided in a guide/doc being created using a specific version of a package.

Thoughts around adding visible tag(s) to docs where code examples are provided to indicate which version of package/language the doc was written for? Maybe directly under the title of the doc in a similar fashion to how we show the date on blog posts.

Example Tags:
AWSX v.1.0.0-beta-7
Python v3.10.12
Go v1.18.9

These tags would serve two purposes:

• Visual indicator to readers to help avoid things like this or this
• Potential to be used for some kind of "needs updating" reporting/automation internally

In regards to the latter, when there are updates to Pulumi packages/required language versions (especially breaking updates), that could be used as the trigger point for some automation to kick off and pull a list of all docs with tags that have values less than the updated version. These "older" docs can be automatically added to a board with a docs/needs-update-review or similar tag.

Questions | Considerations

• How are "breaking changes" detected?

[cnunciato]

As of pulumi/pulumi-hugo#3674, this is now possible -- at least for any code we check into the programs folder, as all dependency files (package.json, go.mod, *.csproj, etc.) are all present and readable. I fiddled with adding a disclosure triangle to show these files as part of the linked PR, but wasn't happy with the UX, so backed it out. But we can definitely do this now once we decide how we want it to look and behave.

[toriancrane]

Hi @cnunciato,

Regarding this comment

But we can definitely do this now once we decide how we want it to look and behave.

Given the original request, I think it makes sense to keep this issue open until we actually have this up and visual. I worry that it will fall to the wayside otherwise, and this way we can keep track of the progress.