[DOCS] Organize breaking changes by component #79162

jrodewig · 2021-10-14T15:06:32Z

Changes

Reorganizes the 8.0 breaking changes and deprecations into component-based categories.
Adds an ESS icon to cluster settings on the ESS user settings allowlist.
Adds tips for sections that aren't relevant to Cloud users.
Updates the labels for some items to provide better context.

Preview

https://elasticsearch_79162.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/migrating-8.0.html

Goals

Make it easier for users to upgrade by grouping similar actions. For example, you can update and remove elasticsearch.yml settings in one go.
Make it easier for users to skip changes that aren't applicable to them.

Out of scope

This PR intentionally does not:

Edit or update the content of any breaking change items.
Combine or split any items.
Test any remediation steps.

This work should be handled as a separate effort.

I'll also need to update the Installation and Upgrade Guide so that we can remove several now-empty files. For now, I've left these files in to avoid breaking the docs build.

Testing

I took care to ensure no breaking changes were lost during the reorganization. In the HTML output, each breaking change has a <summary> tag. You can count these tags as a smoke test.

Get a count for the currently published 8.0 breaking changes:

curl --silent https://www.elastic.co/guide/en/elasticsearch/reference/master/migrating-8.0.html | grep -c -i \<summary

Get a count for the 8.0 breaking changes for this PR:

curl --silent https://elasticsearch_79162.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/migrating-8.0.html | grep -c -i \<summary

The count should match.

elasticmachine · 2021-11-04T22:19:20Z

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

jrodewig · 2021-11-04T22:25:09Z

@pugnascotia @debadair This still has some rough edges, but I'm at a stage where I'd like some feedback. I'm kinda on the fence about whether to proceed or not.

Some areas I'd like feedback on:

Category labels and info architecture. Do these feel right? Are any too narrow or too broad?
Ways to improve the initial visual impact. The cluster settings and REST API sections are pretty long.
Wording for the Cloud tips. These also blend in with the rest of the page. Any suggestions to make them pop more is appreciated.

docs/reference/migration/migrate_8_0/_cluster-node-setting-changes.asciidoc

debadair

The reorg looks great! I left a number of editorial suggestions based on how we're framing the deprecation messages. If I get ambitious, I'll go through the rest, but those are totally optional for getting this merged.

docs/reference/migration/migrate_8_0.asciidoc

docs/reference/migration/migrate_8_0/_cluster-node-setting-changes.asciidoc

pugnascotia

I skimmed over the preview, the reorganized version looks much better. I don't think there's any value to my going through the diffs in detail.

Co-authored-by: debadair <[email protected]>

…eaking-changes

* Reorganizes the 8.0.0 and 8.1.0 breaking changes and deprecations into component-based categories. * Adds an ESS icon to cluster settings on the ESS user settings allowlist. * Adds tips for sections that aren't relevant to Cloud users. * Updates the labels for some items to provide better context. Co-authored-by: debadair <[email protected]> # Conflicts: # docs/reference/migration/index.asciidoc # docs/reference/migration/migrate_8_1.asciidoc

Updates the ES breaking changes headings for elastic/elasticsearch#79162

Removes some unneeded files related to the previous organization of breaking changes. Relates to #79162 and elastic/stack-docs#1877

Following elastic#79162, change the possible breaking / deprecation areas in the changelog schema.

PR #79162 revised the breaking changes categories in the doc. Follow this by revising the categories that changelog YAML files can use.

The structure of the breaking changes / migration guide was updated in #79162 to change the categories and split the breaking changes into different files. This PR amends the changelog generator code in line with this rework.

The change removes a node-level setting. It was accidentally placed with REST API changes as part of #79162. This moves the breaking change to the cluster and node setting changes section.

… (#81220) The change removes a node-level setting. It was accidentally placed with REST API changes as part of #79162. This moves the breaking change to the cluster and node setting changes section.

Combines several 8.0 breaking changes for the removal of API endpoints that contain mapping types. These items were separate because we previously organized breaking changes by area. This is a follow-on to #79162.

… (#81893) Combines several 8.0 breaking changes for the removal of API endpoints that contain mapping types. These items were separate because we previously organized breaking changes by area. This is a follow-on to #79162.

elasticsearchmachine added the v8.0.0 label Oct 14, 2021

jrodewig closed this Oct 26, 2021

jrodewig deleted the docs__reorg-80-breaking-changes branch October 26, 2021 05:35

jrodewig restored the docs__reorg-80-breaking-changes branch October 26, 2021 14:19

jrodewig reopened this Oct 26, 2021

jrodewig mentioned this pull request Oct 26, 2021

Document removal of freeze index API in migration guide #79801

Merged

[DOCS] Reorganize 8.0 breaking changes by component

69bac64

jrodewig added >docs General docs changes v8.1.0 labels Nov 4, 2021

jrodewig marked this pull request as ready for review November 4, 2021 22:19

elasticmachine added the Team:Docs Meta label for docs team label Nov 4, 2021

jrodewig requested review from debadair and pugnascotia November 4, 2021 22:21

jrodewig commented Nov 4, 2021

View reviewed changes

docs/reference/migration/migrate_8_0/_cluster-node-setting-changes.asciidoc Show resolved Hide resolved

debadair approved these changes Nov 6, 2021

View reviewed changes

pugnascotia approved these changes Nov 8, 2021

View reviewed changes

jrodewig and others added 6 commits November 15, 2021 09:43

Apply suggestions from code review

b404596

Co-authored-by: debadair <[email protected]>

Merge remote-tracking branch 'upstream/master' into docs__reorg-80-br…

7aed061

…eaking-changes

add period

4db04c9

remove unneeded tip

51c32ad

remove block

0ac0d8d

hide 8.1 breaking changes

101809c

jrodewig merged commit 767a237 into elastic:master Nov 15, 2021

jrodewig deleted the docs__reorg-80-breaking-changes branch November 15, 2021 15:42

jrodewig mentioned this pull request Nov 15, 2021

[8.0] [DOCS] Organize breaking changes by component (#79162) #80723

Merged

jrodewig added a commit to elastic/stack-docs that referenced this pull request Nov 15, 2021

[DOCS] Update include statements for 8.1 breaking changes (#1878)

6950961

Updates the ES breaking changes headings for elastic/elasticsearch#79162

jrodewig added a commit to elastic/stack-docs that referenced this pull request Nov 15, 2021

[DOCS] Update headings for ES 8.0 breaking changes (#1877)

f40eaa5

Updates the ES breaking changes headings for elastic/elasticsearch#79162

jrodewig added a commit that referenced this pull request Nov 15, 2021

[DOCS] Remove unneeded breaking changes files (#80729)

5061c46

Removes some unneeded files related to the previous organization of breaking changes. Relates to #79162 and elastic/stack-docs#1877

elasticsearchmachine pushed a commit that referenced this pull request Nov 15, 2021

[DOCS] Remove unneeded breaking changes files (#80729) (#80743)

6d840ca

Removes some unneeded files related to the previous organization of breaking changes. Relates to #79162 and elastic/stack-docs#1877

pugnascotia added a commit to pugnascotia/elasticsearch that referenced this pull request Nov 16, 2021

Revise breaking areas in changelog schema

91174e5

Following elastic#79162, change the possible breaking / deprecation areas in the changelog schema.

pugnascotia mentioned this pull request Nov 17, 2021

Revise breaking change doc areas #80761

Merged

pugnascotia added a commit that referenced this pull request Nov 17, 2021

Revise breaking change doc areas (#80761)

38ed63c

PR #79162 revised the breaking changes categories in the doc. Follow this by revising the categories that changelog YAML files can use.

pugnascotia mentioned this pull request Nov 22, 2021

Rework breaking changes for new structure #80907

Merged

jrodewig mentioned this pull request Dec 1, 2021

[DOCS] Relocate 8.0 repositories.fs.compress breaking change #81216

Merged

jrodewig mentioned this pull request Dec 14, 2021

[DOCS] Combine 8.0 breaking changes for mapping type endpoints #81730

Merged

mark-vieira added v8.0.0-rc1 and removed v8.0.0 labels Jan 12, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOCS] Organize breaking changes by component #79162

[DOCS] Organize breaking changes by component #79162

jrodewig commented Oct 14, 2021 •

edited

Loading

elasticmachine commented Nov 4, 2021

jrodewig commented Nov 4, 2021 •

edited

Loading

debadair left a comment •

edited

Loading

pugnascotia left a comment

[DOCS] Organize breaking changes by component #79162

[DOCS] Organize breaking changes by component #79162

Conversation

jrodewig commented Oct 14, 2021 • edited Loading

Changes

Preview

Goals

Out of scope

Testing

elasticmachine commented Nov 4, 2021

jrodewig commented Nov 4, 2021 • edited Loading

debadair left a comment • edited Loading

Choose a reason for hiding this comment

pugnascotia left a comment

Choose a reason for hiding this comment

jrodewig commented Oct 14, 2021 •

edited

Loading

jrodewig commented Nov 4, 2021 •

edited

Loading

debadair left a comment •

edited

Loading