Cross link release notes from breaking changes

[ppf2]

Here is an example on 6.3.

Say someone is upgrading from < 6.3 and looking for breaking changes specific to X-Pack. Where would they go now?

Their natural tendency would be to look for it in either the Elasticsearch breaking changes documentation since we have opened X-Pack (https://www.elastic.co/guide/en/elasticsearch/reference/current/breaking-changes-6.3.html), or in the Stack Overview area (https://www.elastic.co/guide/en/elastic-stack-overview/current/xpack-breaking-changes.html)

The Stack Overview simply links back to the Elasticsearch/Kibana/Logstash breaking changes place. This is fine. Except that the breaking changes we highlight in the ES breaking changes area are all Elasticsearch specific (no information on X-pack).

We ended up putting some of the breaking changes under release notes (https://www.elastic.co/guide/en/elasticsearch/reference/6.3/release-notes-6.3.0.html#breaking-6.3.0). One of which is an important one (where we disable monitoring collection by default now).

Most users looking for breaking changes tend to go straight to the breaking changes section. If the idea here is to only call out the important ones individually in the breaking changes guide, let's make sure to add a cross reference link to the corresponding release notes in the breaking changes guide so that users can go and review "everything". Otherwise, it is easy for the end users to miss some potentially important breaking changes. We currently only have a cross link from release notes back to breaking changes, but not the other way around.

[lcawl]

Just to be clear, the X-Pack-related breaking changes and release notes and release highlights are all merged into the appropriate product-specific pages. The release notes page in the Stack Overview has been removed from master.

[ppf2]

What I am referring to here is not that these things are missing from product-specific pages, but that they are presented in 2 different areas in the documentation with the release notes section having more breaking changes than the actual breaking changes guide, so it will be helpful if we can cross link from breaking changes -> release notes to help guide the end users. Hope this makes sense :)

[lcawl]

If elastic/elasticsearch@4918ae6 is what you had in mind, we can do a similar quick change in Logstash and Kibana refs

[ppf2]

Yep ! ❤️

If there will always be breaking changes that are only in release notes and not directly under the breaking changes section, it will be helpful to explicitly call it out. Example (feel free to rewrite this :D). What do you think?

---

This section discusses the changes that you need to be aware of when migrating your application to Elasticsearch 7.0. Note that not all breaking changes are highlighted in this section. It is important to also review <<es-release-notes>> for additional breaking changes.

See also <<release-highlights>>

[lcawl]

I think if you've found some breaking changes in the release notes that aren't in the breaking changes, that's a mistake. I'll take a look and follow-up on how we can try to avoid this breakage in the future.

[ppf2]

Cool thanks for the help!

[ppf2]

@lcawl @debadair Something doesn't look right with our documentation across products when it comes to breaking changes.

Beats and Kibana breaking changes are also only in the release notes and not under their respective breaking changes sections. If a user goes straight to the breaking changes documentation, they will have the impression that only 6.0 has breaking changes, and not any of the 6.x minors. Can we review all products to ensure that breaking changes are documented not just in release notes but in the actual breaking changes section? Thanks!

[ppf2]

elastic/beats#7368

[lcawl]

I believe we've solved the linking issues now and will continue to keep an eye on the breaking changes.
e.g. https://www.elastic.co/guide/en/elasticsearch/reference/current/breaking-changes-7.1.html
https://www.elastic.co/guide/en/kibana/current/breaking-changes-7.1.html