Add support for *-version attributes in the docs

[bmorelli25]

Summary

We need a way to globally add product versions to the docs. The product versions are primarily used in code blocks for installation instructions. Using a variable in these instructions allows us to easily update code commands as we release product updates.

This tasks requires:

• The ability to add and enable variable substitution in code blocks
• The ability to globally update these variables

Products identified as needing version variables:

• {{context.stack_version}}
• {{context.eck_version}}
• {{context.ece_version}}
• {{context.apm-android_version}}
• {{context.apm-go_version}}
• {{context.apm-os_version}}
• {{context.apm-java_version}}
• {{context.apm-dotnet_version}}
• {{context.apm-nodejs_version}}
• {{context.apm-php_version}}
• {{context.apm-python_version}}
• {{context.apm-ruby_version}}
• {{context.apm-rum_version}}

Release date variables

• {{context.90_release_date}}

Questions from writers:

• Should writers use docset.yml variables in the meantime? The downside of this approach is that we will need to update docset.yml files in at least 30 repositories when 9.0 releases, and then again for every subsequent release.
• Can we standardize on the above variable names (or other var names) so that writers can start updating code blocks to (1) enable substitution and (2) update to the correct variable names?

Helpful regex

This may help you find version attributes that need to be updated: \{\{([^}]*version[^}]*)\}\}

[lcawl]

As per brief chat this morning, I think there's a looming need for guidance if folks start using those attributes a lot. Seems like it was well understood, but for tracking purposes I'm dropping thoughts here too.

1. My assumption is those variables would need to vary. i.e. once we've got "current" and "next" branches of the docs, they'd resolve to 9.0 in the former and 9.1 in the latter, for example.

2. I think we need to provide clear guidance on when it's appropriate to use those variables (i.e. ideally limited to installation- and deployment-specific contexts where we're providing exact commands that must match the exact version number). Otherwise, I'm worried about people using them and not realizing that their text is no longer valid when the version changes in our overall "versionless" context.

3. I think we also need to provide clear guidance on what to do when you have a page that uses these variables but then needs to split off into sibling page. For example, if {{context.stack_version}} is used in code blocks in a page like https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/deploy/self-managed/install-kibana-from-archive-on-linux-macos and then subsequently changes so much that we need to split off a V9.0 and V9.1 or V10.0 sibling page, then we'd need clear guidance about what ought to be done for the variables in each page. Should they:

   • keep using the {{context.stack_version}} in the "current" variation and hard-code the version in the older release variations?
   • " " and create a docset-level or page-level substitution for the version in the older release variations?

Either way, it seems like it means if 9.1 and 9.0 continue to coexist and get releases for quite a while, that it might be a pain for folks to likewise maintain all the docset- or page-level stack_version_90 substitutions. Should we consider creating them as context variables instead? For example: {{context.stack_version}}, {{context.stack_version_90}}, and {{context.stack_version_91}}, with the expectation that the latter two are used only in the sibling page use case? Or do we want to actively discourage the need for sibling pages as much as possible and thus leave them as point-in-time hard-coded values (e.g. in the 9.0 variation) when we've moved on to having 9.1 as current?

[colleenmcginnis]

This functionality would also be helpful for release dates in the release notes. I suspect it might get tricky to maintain these across repos (we already have to open PRs across all repos using Stack versioning because the 9.0 release date changed....).

[timto-elastic]

To @lcawl's point, we are versionless in v9 with minor and patch content labeled with applies_to. This means we will have to support multiple minors in examples and other version specific things (ie, it depends on what minor you are on or interested in) and the implication is that just the latest stack version isn't enough. In the curl example above:
curl -O https://artifacts.elastic.co/downloads/kibana/kibana-**9.0.0**-darwin-x86_64.tar.gz
We would most likely have a single page since only the version portion of the string is different. You would need to pick the right version if not the default (assuming we default to latest). We could do this in tabs, we could do this in separate pages, we could do this with a version picker/filter (default to a picked version). The last one seems to be the most natural. In any case, we need a way to specify specific minor (or maybe in some cases even patch). Either we do version variants manually or autogenerated (eg, like an array with all versions that we can simply pick the one we want to use).

That said, we should definitely have the variables above for the static use cases.

[colleenmcginnis]

Here's a concrete example of where we might need to use version variables (now that 9.0.1 has been released): elastic/docs-content#1373.

[lcawl]

I also had some comments in elastic/elasticsearch-hadoop#2378 where I think we'll need to have more context-specificity (e.g. "stack-current-version" and "stack-next-version" variables (or even more specific "stack-90-version" and "stack-91-version" for situations where both will co-exist on a branch)