search

elastic / elasticsearch

Free and Open Source, Distributed, RESTful Search Engine
https://www.elastic.co/products/elasticsearch
Other
1.08k stars 24.84k forks source link

Formalize "known issues" docs concept #111024

Open DaveCTurner opened 3 months ago

DaveCTurner commented 3 months ago

Today if we want to call out a known issue in a released version we just add a new ad-hoc item to the release notes of all affected versions. This is kind of a pain, and it's easy to miss versions or for the notes to end up inconsistent across branches/backports etc. See for instance the docs fixes in https://github.com/elastic/elasticsearch/pull/111014.

Could we instead introduce a more formal entity to represent each known issue, perhaps something like the file-per-PR changelog structure, to make it harder to make mistakes or miss copying the known issue docs to all the right places?

elasticsearchmachine commented 3 months ago

Pinging @elastic/es-core-infra (Team:Core/Infra)

elasticsearchmachine commented 3 months ago

Pinging @elastic/es-docs (Team:Docs)

rjernst commented 2 months ago

We discussed this in the core/infra sync and agree it would be a good feature. Restating what we think is being proposed, we would have a directory of files, one for each known issue, with some metadata about the known issue like a description and what versions it applies to. Then, when building the release notes, we would iterate through this directory, much like we do with the changelog today, so that we don't need to manually edit the release notes with known issues.

Although we are in favor of this, it doesn't seem like core/infra, so I'm passing off to delivery since they own the release notes tooling.

elasticsearchmachine commented 2 months ago

Pinging @elastic/es-delivery (Team:Delivery)