[DOCS] Clarify backport policy for important technical corrections. #49131
Conversation
|
Pinging @elastic/es-docs (:Docs) |
Co-Authored-By: James Rodewig <[email protected]>
docs/README.asciidoc
Outdated
| (as applicable). | ||
|
|
||
| * Important technical corrections that need to be applied to the maintenance version of the | ||
| previous major version also need to be applied to all intervening minor versions. |
There was a problem hiding this comment.
I'm not sure that I agree with this part. This is where the guidance would be deviating from what we do for code. For example, with this guidance, if we applied a doc fix to 6.8, then it would mean we also apply it to 7.0, 7.1, 7.2, 7.3 even though we are no longer maintaining those versions. We don't do that for code, and what I'm hoping for is that we can have the same guidance for code as for docs.
There was a problem hiding this comment.
That's where I started, but there was some discomfort with having discrepancies as you move forward in the docs.
The nature of the docs is a bit different from the releases, as users can and do end up looking at docs for a different version than they're running, and people frequently flip between versions of the docs to see when changes were introduced. Merging the changes through all intervening versions also sets a pretty high bar for what changes warrant that level of effort.
That said, deviating from what we do for code complicates things, and a blanket policy that "out of maintenance" means no further changes would be significantly easier.
It feels like a bit of a trade-off between optimizing for the contributor experience and optimizing for the user experience. If we opt for a consistent policy and freeze the docs for out of maintenance versions, I think we need to clearly communicate that to folks looking at those versions.
There was a problem hiding this comment.
The nature of the docs is a bit different from the releases, as users can and do end up looking at docs for a different version than they're running, and people frequently flip between versions of the docs to see when changes were introduced.
We have changelogs, and release notes (which we are working on improving), I'm not sure if we should design our backport policy around this workflow that our docs aren't otherwise designed for (e.g., we feel free to reorganize our docs in minor releases, which breaks this workflow, among others).
Merging the changes through all intervening versions also sets a pretty high bar for what changes warrant that level of effort.
I'm not sure if that's a feature. It could mean that we end up dis-favoring backporting changes to the maintained version of the previous major which is hurtful to those users, and somewhat unexpected. It is still a maintained version, after all. I don't think we want to make the cost of backporting so high that we discourage backporting to a maintained version (e.g., when we get to 7.10, backporting to 7.0--7.9 really highlights how onerous it is).
It feels like a bit of a trade-off between optimizing for the contributor experience and optimizing for the user experience. If we opt for a consistent policy and freeze the docs for out of maintenance versions, I think we need to clearly communicate that to folks looking at those versions.
I think it would make for a clear policy (and I do agree we should be transparent about it). We do a draw a line (e.g., I don't think anyone would disagree that we aren't going to backport doc changes to 6.4, or 5.5, or 2.4...). I don't see much of a difference between 6.4 and 7.1, both are unmaintained, and we are already clear about that from a code perspective.
At the end, maintenance is a cost, and it's a steep one because it eats our most precious resource: time.
There was a problem hiding this comment.
FWIW, sentiment amongst the writers leans toward being consistent with the code policy and not backporting doc changes to out of maintenance versions. Personally, I think there are valid reasons to choose either option--I think it's more important that we're consistent and clear about what the policy is than which option we choose.
There was a problem hiding this comment.
I'm in favor of being consistent with the code policy with the dependency that we place stronger language in our unmaintained docs to highlight this (as Deb mentioned in another issue). I was just working with a large user running ES 6.3, they know they need to upgrade, but are still checking 6.3 docs. Stronger language could make it more clear they're looking at out-of-date material (instead of the current language "You are looking at documentation for an older release") .
There was a problem hiding this comment.
I'm fine with following the code policy, but with 2 caveats:
- I agree with @zuketo we should have warnings indicating the docs are for an unmaintained version and could be out of date.
- We should stop building the unmaintained versions? Currently we have crons to rebuild all branches of the current major, afaik.
There was a problem hiding this comment.
It seems that we are all in agreement that we should more clearly indicate that docs corresponding to unmaintained versions are unmaintained. That said, I think that disabling docs builds for them would be a bridge too far. The policy that we are agreeing to here is that we should backport to same versions that we would backport code changes to (with similar caveats around complexity of the backport, etc.). However, the policy is not that we wouldn't backport to any unmaintained version, I can see occasions where we might, and we would want docs builds in those cases. Docs builds are cheaper these days, with all the investment made in the docs infrastructure.
There was a problem hiding this comment.
As long as we're still publishing the unmaintained versions to the website, we need to be able to rebuild them if we have to (because of website changes, design changes, or some unforseen circumstance). The easiest way to ensure that's possible is to keep them in the doc build.
There's a related discussion about removing old versions going on here: elastic/docs#1419.
I can craft some updated out of maintenance/EOL notices, and I'll update this PR to align with the code policy.
Co-Authored-By: James Rodewig <[email protected]>
|
Proposed OOM & EOL notices: elastic/docs#1426 @rjernst @jasontedor Are the changes in this PR okay to merge? |
…49131) * [DOCS] Clarify backport policy for important technical corrections. * Update docs/README.asciidoc Co-Authored-By: James Rodewig <[email protected]>
…49131) * [DOCS] Clarify backport policy for important technical corrections. * Update docs/README.asciidoc Co-Authored-By: James Rodewig <[email protected]>
…49131) * [DOCS] Clarify backport policy for important technical corrections. * Update docs/README.asciidoc Co-Authored-By: James Rodewig <[email protected]>
Updated based on feedback from @rjernst and @jasontedor.
If a technical correction warrants being applied to the maintenance version of the previous major, it should also be applied to all applicable minor versions in the current major, including those that are out of maintenance. If it's important enough to update the maintenance version of the previous major, it's worth expending the effort to apply it to the intervening minor versions.