[DOCS] Add option to make GH issue link required for experimental/beta macros

[jrodewig]

We add the experimental::[] and beta::[] macros to Elasticsearch documentation not ready for GA. However, these tags don't currently indicate what steps are needed to get a feature to GA.

To solve this, we can require a related GH issue link for any experimental::[] or beta::[] tag. We should investigate whether that requirement is technically feasible in our docs build and tests.

To Do

• Add arg for issue links to beta::[] and experimental::[] block macros. _source field not being returned when a script field is specified elasticsearch#1705

• Create a doc build option flag to enable/disable link checks for beta::[] and experimental::[] block macros. This flag should be settable in conf.yaml and default to false to avoid impacting other doc books.

  When enabled, this flag should only work on the latest branch (e.g. master for Elasticsearch). This means we won't have to update the macros in branches that are no longer maintained.

  See Introduce MIGRATION warnings #686 for a loose example.

• Create an Asciidoctor preprocessor extension to check for links or {issue} attributes in the beta::[] and experimental::[] block macros. The extension should emit a warning if the link is not included.

  See /elastic_compat_preprocessor/extension.rb for an example preprocessor extension with logic for catching beta and experimental block macros.

  See migration_log.rb for an example warning implementation.

• Enable the link check option for the Elasticsearch book build in conf.yaml.

[elasticmachine]

Pinging @elastic/es-docs (:Docs)

[nik9000]

To solve this, we can require a related GH issue link for any [[experimental]] or [[beta]] tag. We should investigate whether that requirement is technically feasible in our docs build or tests.

The docs have a "migration" warning mechanism that we can use to make this a requirement only for the master branch. OTOH, it'd make this a requirement across all docs, not just Elasticsearch. I can't quite tell how many docs have warnings without a little more work than I'd like to do right now.

[nik9000]

We can certainly make the experimental and beta macros take an argument for the issue url and add the link.

[jrodewig]

We can certainly make the experimental and beta macros take an argument for the issue url and add the link.

I put up a PR to support the GitHub issue arg here: #1705

That should make it easier to link GitHub issues, but it's still not the forcing function we're looking for. I'll also plan to research the migration warning mechanism @nik9000 mentioned.

[jrodewig]

I added a "To do" section to this issue based on my research.

This confirms requiring the links is feasible, but it'll take a non-trivial development effort. However, I'm not an experienced developer so there might be better solutions I'm not aware of.

I've also transferred this ticket to the elastic/docs repo, where most of the work will need to take place. While the Elasticsearch team requested this feature, it could be used by other doc books.

I'm unassigning myself from this ticket. While I may attempt to work on these tasks as time permits, my progress is likely to be slow.

[jrodewig]

Closing this as it's no longer a priority with the new docs system.