Solve versioning between VPR and stack docs
- Dominant language
- Ruby
- Stars
- 4
- Forks
- 12
- PR merge metrics
- No merged PRs in 30d
Description
### Summary
The [Versioned Plugin Reference (VPR)](https://www.elastic.co/guide/en/logstash-versioned-plugins/current/index.html) should point to the version of stack and ECS docs that were current when each plugin version was released.
The [Logstash Reference](https://www.elastic.co/guide/en/logstash/current/index.html) 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](https://www.elastic.co/guide/en/logstash-versioned-plugins/current/output-elasticsearch-index.html)) That's why it makes sense to set the branch version as an attribute instead of handling it dynamically.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.