Skip to content

[DOCS] Clarify backport policy for important technical corrections. #49131

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Nov 20, 2019
Merged

[DOCS] Clarify backport policy for important technical corrections. #49131

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
64b8d89
[DOCS] Clarify backport policy for important technical corrections.
debadair Nov 15, 2019
fc1aaf3
Update docs/README.asciidoc
debadair Nov 15, 2019
2307946
Update docs/README.asciidoc
debadair Nov 15, 2019
e261ac0
Update docs/README.asciidoc
debadair Nov 15, 2019
970f530
Incorporated feedback.
debadair Nov 19, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 16 additions & 12 deletions docs/README.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,24 @@ See: https://github.com/elastic/docs

=== Backporting doc fixes

* Doc bug fixes and enhancements to existing content should be made against master
and backported as far as the current version. Backporting doc changes to earlier minor versions
that are out of maintenance is often complicated due to content restructuring and is not required.

* Backport important fixes such as security updates that have a direct customer impact to all affected versions.

* Avoid backporting doc changes across major versions unless it’s an important fix or
the change is related to upgrading from the last minor version of the previous major.

* Doc changes should generally be made against master and backported through to the current version
(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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@rjernst, @zuketo?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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") .

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@debadair debadair Nov 19, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


* Routine doc fixes and enhancements generally should not be backported to minor versions
that are out of maintenance or across major versions.
The time required to resolve complex merge conflicts and test failures or figure out where
to apply the change when the content structure has changed is better spent making additional
improvements.

* Doc PRs opened against out of maintenance, non-EOL versions can be merged to that version.
Where applicable, the change should be applied to master and backported through
to the current version.

* Do not backport doc changes to https://www.elastic.co/support/eol[EOL versions].

* Doc PRs opened against released (non-EOL) versions can be merged to that version,
applied to master, and backported to the current version (where applicable).

=== Snippet testing

Snippets marked with `[source,console]` are automatically annotated with
Expand Down