Introduce substitutions for previous versions

[cotti]

Closes #2092

[github-actions]

🔍 Preview links for changed docs

• docs/syntax/substitutions.md

[Mpdreamz]

I am not in love with with the previous moniker.

Could this be a mutation? e.g

{{ .elasticsearch | version_legacy }}

Ideally we can support version and base also as mutations

{{ .elasticsearch | version }}
{{ .elasticsearch | version_base }} ?

[Mpdreamz]

Ensure VersioningSystems is correct and we can read it.

e.g add system.Legacy as an additional property so we can keep on simply itterating on VersioningSystems

[shainaraskas]

I am not in love with with the previous moniker.

legacy is not ideal either. it's a legacy-ish docs system, but the products are still in active support. while this term is good enough for me, I could see it being confusing for contributors and maybe sending the wrong message for users looking under the hood.

likewise, while I appreciate that this is a straightforward way to make this change, it's not going to be robust long term (i.e. once we hit a new major). the info we actually want here is "the last minor of the previous major", which will break down when we move to stack 10 and 9.x docs are accessible in a way other than traversing mapped pages. I'd rather just see this as another piece of info stored in versions.yml ... we can avoid adding it until it's needed, product by product.

alt: we just store this as a sub in docset.yml. again, we don't need this for all products afaik (maybe @colleenmcginnis can correct me if she sees a big need for this in ingest tool land)

[colleenmcginnis]

alt: we just store this as a sub in docset.yml. again, we don't need this for all products afaik (maybe @colleenmcginnis can correct me if she sees a big need for this in ingest tool land)

Nope. I don't see any need for this in ingest docs. For the most part we just refer to 8.19 (minor only).

[shainaraskas]

Finally, this actually doesn't do what I think @eedugon was asking for. I think edu wants to specify down to the patch version, and this just pulls the minor because it's using the mapped page info, which is not aware of the patch version.

[eedugon]

I agree with @shainaraskas , we need something that substitutes to 8.16.6 today, and whenever we deliver a new patch release the substitution will change to 8.19.7, etc.

Getting 8.19 almost doesn't add any benefit as that's not going to change in the next 2 years.

[cotti]

I see. Yeah, the need for the patch version means the initial premise here of picking this information from legacy url mappings isn't good enough.

We can add this information to versions.yml, is this worth pursuing this change?

[shainaraskas]

@cotti I think this is mostly a nice to have feature but not critical. might be worth doing if it's trivially easy

[eedugon]

@cotti , @shainaraskas : if we want to automate this and go to the source of truth of that version I'd say that we can get it from the legacy elastic/docs repository.

The file /shared/versions/stack/8.19.asciidoc has the latest patch on the first line:

:version:                8.19.6

And it would be automatically updated after every release :)

So if we can make docs-builder to fetch it we wouldn't need to manually touch docs-V3 after releasing a 8.19 version.

But keeping it in versions.yaml and just manually updating it after every 8.19 release is also a good approach, happy with that also.