search

elastic / docs-tools

A place to put documentation tooling
4 stars 13 forks source link

Solve versioning between VPR and stack docs #46

Open karenzone opened 3 years ago

karenzone commented 3 years ago

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

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 commented 3 years ago

@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 commented 2 years ago

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 commented 2 years ago

Here's an example of how I fixed this for 8.0 by adding an attribute for stack version: https://github.com/elastic/logstash-docs/pull/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 commented 2 years ago

Next steps:

karenzone commented 2 years ago

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