Solve versioning between VPR and stack docs

[karenzone]

Summary

The Versioned Plugin Reference (VPR) should point to the version of stack and ECS docs that were current when each plugin version was released.
The Logstash Reference understands stack versioning, and this problem doesn't exist for plugin docs published there.

Goals

• Avoid broken docs builds due to link changes and version mismatches
• Move away from current in our doc paths
• Help remove confusion for our users. Example: Deprecation notices in our plugins mention the plugin version only. There's no easy way for users to see a plugin version (that is older than current version) and map it to a Logstash version.

Current implementation

The workaround is to set the version to current here: https://github.com/elastic/logstash-docs/edit/versioned_plugin_docs/docs/versioned-plugins/index.asciidoc (Lines 10-22).
This approach causes problems when link targets are updated, renamed, or deleted. Plus, we're trying to move away from using current in our docs, in general. (See https://github.com/elastic/elastic-docs/issues/133.)

Out of 200+ plugins, this issue affects only 8-10. Not all plugins need to link back to stack or ECS docs.

Proposal

The docgen script for versioned plugins should add a version attribute near the top of the generated file, and then clear the setting at the end of the file to avoid spillover into other plugins (although this approach would leave a gap between FF and release).
Another idea: Look at branch and/or tags in logstash-docs as source of truth.

:branch: 7.12
:ecs-version: 1.8

Ideally, we can pick up the version information from places we set it currently, such as https://github.com/elastic/docs/tree/master/shared/versions/stack.

Random notes

Each plugin doc in the VPR is a one-off. (Examples) That's why it makes sense to set the branch version as an attribute instead of handling it dynamically.

[karenzone]

@glitteringkatie had an interesting proposal for the new docs system that would alleviate a portion of the versioning problems. If we don't specify a branch, assume current (or equivalent) as the default while still allowing for overrides when needed.

[karenzone]

Added to issue overview:

"* Help remove confusion for our users. Example: Deprecation notices in our plugins mention the plugin version only. There's no easy way for users to see a plugin version (that is older than current version) and map it to a Logstash version to know the timeframe the item was deprecated. "

There are likely other examples, too. This is the most recent I've encountered and I wanted to capture it so we could dig deeper. The user issue goes deeps than just versioning logistics, but a good solution around logistics could help.

Another idea: Could we make available an easily accessible mapping table to [roughly] map plugin versions to stack versions? Keep grooving on this...

[karenzone]

Here's an example of how I fixed this for 8.0 by adding an attribute for stack version: elastic/logstash-docs#1289

Focus on Line 4 where I added the {branch} attribute. The other work in the PR is to set everything up so that attribute will actually be used.

[karenzone]

Next steps:

• Karen: Test implementation on a single plugin: [input-file] Doc: Set version attribute in plugin source file #308
• Karen: Evaluate exposing version information relevant to this comment: Solve versioning between VPR and stack docs #46 (comment)
• Karen: Implement on relevant plugins (mini-meta issue to come)

[karenzone]

Reopening issue.
Phase 1 was complete with #70. ✅
Implementation, testing, and fixing old entries remains to be done.