[DOCS] Remove breaking change tags (#98144)

With elastic/stack-docs#2495 merged, we no longer reuse breaking changes in the Stack Install/Upgrade guide. This removes the related `notable-breaking-changes[]` tags from the 8.9+ docs and updates the RN generator template. ## Out of scope With the removal of these tags, we may no longer need the `notable` property for changelog entries and can likely simplify the logic for the [BreakingChangesGenerator](https://github.com/elastic/elasticsearch/blob/main/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/BreakingChangesGenerator.java). Updating those files is outside the scope of this PR. I've opened #98145 to track that work.
elastic · Aug 3, 2023 · e00b354 · e00b354
1 parent 2076183
commit e00b354
Show file tree

Hide file tree

Showing 26 changed files with 1 addition and 140 deletions.
diff --git a/build-tools-internal/src/main/resources/templates/breaking-changes.asciidoc b/build-tools-internal/src/main/resources/templates/breaking-changes.asciidoc
@@ -16,32 +16,21 @@ coming::[${majorDotMinorDotRevision}]
 [[breaking-changes-${majorDotMinor}]]
 === Breaking changes
 <% if (breakingByNotabilityByArea.isEmpty()) { %>
-// tag::notable-breaking-changes[]
 There are no breaking changes in {es} ${majorDotMinor}.
-// end::notable-breaking-changes[]
 <% } else { %>
 The following changes in {es} ${majorDotMinor} might affect your applications
 and prevent them from operating normally.
 Before upgrading to ${majorDotMinor}, review these changes and take the described steps
 to mitigate the impact.
-
 <%
     if (breakingByNotabilityByArea.getOrDefault(true, []).isEmpty()) { %>
-// tag::notable-breaking-changes[]
+
 There are no notable breaking changes in {es} ${majorDotMinor}.
-// end::notable-breaking-changes[]
 But there are some less critical breaking changes.
 <%  }
     [true, false].each { isNotable ->
         def breakingByArea = breakingByNotabilityByArea.getOrDefault(isNotable, [])
         if (breakingByArea.isEmpty() == false) {
-            if (isNotable) {
-                /* No newline here, one will be added below */
-                print "// NOTE: The notable-breaking-changes tagged regions are re-used in the\n"
-                print "// Installation and Upgrade Guide\n"
-                print "// tag::notable-breaking-changes[]"
-            }
-
             breakingByArea.eachWithIndex { area, breakingChanges, i ->
                 print "\n[discrete]\n"
                 print "[[breaking_${majorMinor}_${ area.toLowerCase().replaceAll("[^a-z0-9]+", "_") }_changes]]\n"
@@ -62,9 +51,6 @@ ${breaking.impact.trim()}
                 }
             }
 
-            if (isNotable) {
-                print "// end::notable-breaking-changes[]\n"
-            }
         }
     }
 }
@@ -83,16 +69,10 @@ after upgrading to ${majorDotMinor}.
 
 To find out if you are using any deprecated functionality,
 enable <<deprecation-logging, deprecation logging>>.
-
 <%
     [true, false].each { isNotable ->
         def deprecationsByArea = deprecationsByNotabilityByArea.getOrDefault(isNotable, [])
         if (deprecationsByArea.isEmpty() == false) {
-            if (isNotable) {
-                /* No newline here, one will be added below */
-                print "// tag::notable-breaking-changes[]"
-            }
-
             deprecationsByArea.eachWithIndex { area, deprecations, i ->
                 print "\n[discrete]\n"
                 print "[[deprecations_${majorMinor}_${ area.toLowerCase().replaceAll("[^a-z0-9]+", "_") }]]\n"
@@ -113,9 +93,6 @@ ${deprecation.impact.trim()}
                 }
             }
 
-            if (isNotable) {
-                print "// end::notable-breaking-changes[]\n"
-            }
         }
     }
 } %>
diff --git a/...le/internal/release/BreakingChangesGeneratorTest.generateMigrationFile.asciidoc b/...le/internal/release/BreakingChangesGeneratorTest.generateMigrationFile.asciidoc
@@ -21,9 +21,6 @@ and prevent them from operating normally.
 Before upgrading to 8.4, review these changes and take the described steps
 to mitigate the impact.
 
-// NOTE: The notable-breaking-changes tagged regions are re-used in the
-// Installation and Upgrade Guide
-// tag::notable-breaking-changes[]
 [discrete]
 [[breaking_84_api_changes]]
 ==== API changes
@@ -64,7 +61,6 @@ Breaking change details 4
 *Impact* +
 Breaking change impact description 4
 ====
-// end::notable-breaking-changes[]
 
 [discrete]
 [[breaking_84_transform_changes]]
@@ -95,7 +91,6 @@ after upgrading to 8.4.
 To find out if you are using any deprecated functionality,
 enable <<deprecation-logging, deprecation logging>>.
 
-// tag::notable-breaking-changes[]
 [discrete]
 [[deprecations_84_cluster_and_node_setting]]
 ==== Cluster and node setting deprecations
@@ -121,7 +116,6 @@ Deprecation change details 6
 *Impact* +
 Deprecation change impact description 6
 ====
-// end::notable-breaking-changes[]
 
 [discrete]
 [[deprecations_84_cluster_and_node_setting]]

diff --git a/docs/reference/migration/migrate_8_0.asciidoc b/docs/reference/migration/migrate_8_0.asciidoc
@@ -46,9 +46,6 @@ after upgrading to 8.0.
 To find out if you are using any deprecated functionality,
 enable <<deprecation-logging, deprecation logging>>.
 
-//NOTE: The notable-breaking-changes tagged regions are re-used in the
-//Installation and Upgrade Guide
-//tag::notable-breaking-changes[]
 [discrete]
 [[breaking_80_cluster_node_setting_deprecations]]
 ==== Cluster and node setting deprecations
@@ -92,7 +89,6 @@ Passwords are generated automatically for the `elastic` user when you start {es}
 starting {es}, it will fail because the `elastic`
 user password is already configured.
 ====
-//end::notable-breaking-changes[]
 
 include::migrate_8_0/migrate_to_java_time.asciidoc[]
 include::transient-settings-migration-guide.asciidoc[]
diff --git a/docs/reference/migration/migrate_8_0/cluster-node-setting-changes.asciidoc b/docs/reference/migration/migrate_8_0/cluster-node-setting-changes.asciidoc
@@ -2,10 +2,6 @@
 [[breaking_80_cluster_node_setting_changes]]
 ==== Cluster and node setting changes
 
-//NOTE: The notable-breaking-changes tagged regions are re-used in the
-//Installation and Upgrade Guide
-
-//tag::notable-breaking-changes[]
 TIP: {ess-setting-change}
 
 .`action.destructive_requires_name` now defaults to `true`. {ess-icon}
@@ -884,7 +880,6 @@ repository-specific `compress` setting to enable compression instead. Refer to
 {ref}/snapshots-filesystem-repository.html#filesystem-repository-settings[Shared
 file system repository settings].
 ====
-//end::notable-breaking-changes[]
 
 // This change is not notable because it should not have any impact on upgrades
 // However we document it here out of an abundance of caution
@@ -911,7 +906,6 @@ Any node that did not have an explicitly configured password hashing algorithm i
 {es} 6.x or {es} 7.x would have failed to start.
 ====
 
-//tag::notable-breaking-changes[]
 .The `xpack.monitoring.history.duration` will not delete indices created by metricbeat or elastic agent
 [%collapsible]
 ====
@@ -935,4 +929,3 @@ metricbeat or agent to collect monitoring data, you can also remove any custom `
 settings.
 
 ====
-// end::notable-breaking-changes[]
diff --git a/docs/reference/migration/migrate_8_0/command-line-tool-changes.asciidoc b/docs/reference/migration/migrate_8_0/command-line-tool-changes.asciidoc
@@ -2,10 +2,6 @@
 [[breaking_80_command_line_tool_changes]]
 ==== Command line tool changes
 
-//NOTE: The notable-breaking-changes tagged regions are re-used in the
-//Installation and Upgrade Guide
-
-//tag::notable-breaking-changes[]
 TIP: {ess-skip-section}
 
 [[migrate-tool-removed]]
@@ -22,4 +18,3 @@ realm directly.
 Discontinue use of the `elasticsearch-migrate` tool. Attempts to use the
 `elasticsearch-migrate` tool will result in an error.
 ====
-//end::notable-breaking-changes[]
diff --git a/docs/reference/migration/migrate_8_0/index-setting-changes.asciidoc b/docs/reference/migration/migrate_8_0/index-setting-changes.asciidoc
@@ -2,10 +2,6 @@
 [[breaking_80_index_setting_changes]]
 ==== Index setting changes
 
-//NOTE: The notable-breaking-changes tagged regions are re-used in the
-//Installation and Upgrade Guide
-
-//tag::notable-breaking-changes[]
 [[deprecation-system-indices]]
 .Direct access to system indices is deprecated.
 [%collapsible]
@@ -124,4 +120,3 @@ Discontinue use of the `index.translog.retention.age` and
 `index.translog.retention.size` index settings. Requests that
 include these settings will return an error.
 ====
-//end::notable-breaking-changes[]
diff --git a/docs/reference/migration/migrate_8_0/java-api-changes.asciidoc b/docs/reference/migration/migrate_8_0/java-api-changes.asciidoc
@@ -2,10 +2,6 @@
 [[breaking_80_java_api_changes]]
 ==== Java API changes
 
-//NOTE: The notable-breaking-changes tagged regions are re-used in the
-//Installation and Upgrade Guide
-
-//tag::notable-breaking-changes[]
 [[ilm-hlrc-rename]]
 .The `indexlifecycle` package has been renamed `ilm` in the Java High Level REST Client.
 [%collapsible]
@@ -52,4 +48,3 @@ testability.
 *Impact* +
 No action needed.
 ====
-//end::notable-breaking-changes[]
diff --git a/docs/reference/migration/migrate_8_0/jvm-option-changes.asciidoc b/docs/reference/migration/migrate_8_0/jvm-option-changes.asciidoc
@@ -2,10 +2,6 @@
 [[breaking_80_jvm_option_changes]]
 ==== JVM option changes
 
-//NOTE: The notable-breaking-changes tagged regions are re-used in the
-//Installation and Upgrade Guide
-
-//tag::notable-breaking-changes[]
 TIP: {ess-skip-section}
 
 [[breaking_80_allocation_change_flood_stage_block_always_removed]]
@@ -56,4 +52,3 @@ system property, and ensure that all nodes of the same version are running
 exactly the same build. Setting this system property will result in an error
 on startup.
 ====
-//end::notable-breaking-changes[]
diff --git a/docs/reference/migration/migrate_8_0/logging-changes.asciidoc b/docs/reference/migration/migrate_8_0/logging-changes.asciidoc
@@ -2,10 +2,6 @@
 [[breaking_80_logging_changes]]
 ==== Logging changes
 
-//NOTE: The notable-breaking-changes tagged regions are re-used in the
-//Installation and Upgrade Guide
-
-//tag::notable-breaking-changes[]
 .{es} JSON logs now comply with ECS.
 [%collapsible]
 ====
@@ -55,4 +51,3 @@ to use the new names and to possibly account for `gzip` archives instead of
 plain text. The Docker build of {es} is not affected because it logs on `stdout`,
 where rollover is not performed.
 ====
-//end::notable-breaking-changes[]
diff --git a/docs/reference/migration/migrate_8_0/mapping-changes.asciidoc b/docs/reference/migration/migrate_8_0/mapping-changes.asciidoc
@@ -2,10 +2,6 @@
 [[breaking_80_mapping_changes]]
 ==== Mapping changes
 
-//NOTE: The notable-breaking-changes tagged regions are re-used in the
-//Installation and Upgrade Guide
-
-//tag::notable-breaking-changes[]
 .Indices created in {es} 6.x and earlier versions are not supported.
 [%collapsible]
 ====
@@ -135,4 +131,3 @@ GitHub or the 'discuss' forums.
 Discontinue use of the `sparse_vector` field data type. Requests containing
 a mapping for this field data type will return an error.
 ====
-//end::notable-breaking-changes[]
diff --git a/docs/reference/migration/migrate_8_0/packaging-changes.asciidoc b/docs/reference/migration/migrate_8_0/packaging-changes.asciidoc
@@ -2,10 +2,6 @@
 [[breaking_80_packaging_changes]]
 ==== Packaging changes
 
-//NOTE: The notable-breaking-changes tagged regions are re-used in the
-//Installation and Upgrade Guide
-
-//tag::notable-breaking-changes[]
 TIP: {ess-skip-section}
 
 .The layout of the data folder has changed.
@@ -62,4 +58,3 @@ After the geoip downloader has completed downloading the most up to data databas
 then the geoip processor will function as normal. The window of time that the
 geoip processor can't do geoip lookups after cluster startup should be very small.
 ====
-//end::notable-breaking-changes[]
diff --git a/docs/reference/migration/migrate_8_0/painless-changes.asciidoc b/docs/reference/migration/migrate_8_0/painless-changes.asciidoc
@@ -2,10 +2,6 @@
 [[breaking_80_painless_changes]]
 ==== Painless changes
 
-//NOTE: The notable-breaking-changes tagged regions are re-used in the
-//Installation and Upgrade Guide
-
-//tag::notable-breaking-changes[]
 .The `JodaCompatibleZonedDateTime` class has been removed.
 [%collapsible]
 ====
@@ -44,4 +40,3 @@ The following `JodaCompatibleZonedDateTime` methods must be replaced using
 * `toString(String)` -> a DateTimeFormatter
 * `toString(String, Locale)` -> a DateTimeFormatter
 ====
-//end::notable-breaking-changes[]
diff --git a/docs/reference/migration/migrate_8_0/plugin-changes.asciidoc b/docs/reference/migration/migrate_8_0/plugin-changes.asciidoc
@@ -2,10 +2,6 @@
 [[breaking_80_plugin_changes]]
 ==== Plugin changes
 
-//NOTE: The notable-breaking-changes tagged regions are re-used in the
-//Installation and Upgrade Guide
-
-//tag::notable-breaking-changes[]
 TIP: {ess-skip-section}
 
 .The S3, GCS and Azure repository plugins are now included in Elasticsearch
@@ -66,5 +62,3 @@ check with the plugin author and ensure that the plugin is available for your
 target version of {es} before upgrading.
 
 ====
-
-//end::notable-breaking-changes[]
diff --git a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc
@@ -2,10 +2,6 @@
 [[breaking_80_rest_api_changes]]
 ==== REST API changes
 
-//NOTE: The notable-breaking-changes tagged regions are re-used in the
-//Installation and Upgrade Guide
-
-//tag::notable-breaking-changes[]
 .REST API endpoints containing `_xpack` have been removed.
 [%collapsible]
 ====
@@ -1140,4 +1136,3 @@ for both cases.
 *Impact* +
 To detect a server timeout, check the `timed_out` field of the JSON response.
 ====
-//end::notable-breaking-changes[]
diff --git a/docs/reference/migration/migrate_8_0/sql-jdbc-changes.asciidoc b/docs/reference/migration/migrate_8_0/sql-jdbc-changes.asciidoc
@@ -2,10 +2,6 @@
 [[breaking_80_jdbc_changes]]
 ==== SQL JDBC changes
 
-//NOTE: The notable-breaking-changes tagged regions are re-used in the
-//Installation and Upgrade Guide
-
-//tag::notable-breaking-changes[]
 .JDBC driver returns geometry objects as well-known-text string instead of `org.elasticsearch.geo` objects.
 [%collapsible]
 ====
@@ -24,4 +20,3 @@ Elasticsearch JDBC driver with their WKT representation by simply calling `toStr
 This change does NOT impact users that do not use geometry classes.
 
 ====
-// end::notable-breaking-changes[]
diff --git a/docs/reference/migration/migrate_8_0/system-req-changes.asciidoc b/docs/reference/migration/migrate_8_0/system-req-changes.asciidoc
@@ -2,10 +2,6 @@
 [[breaking_80_system_req_changes]]
 ==== System requirement changes
 
-//NOTE: The notable-breaking-changes tagged regions are re-used in the
-//Installation and Upgrade Guide
-
-//tag::notable-breaking-changes[]
 TIP: {ess-skip-section}
 
 .Several EOL operating systems are no longer supported.
@@ -61,4 +57,3 @@ the bundled JDK (preferable), or set `ES_JAVA_HOME`.
 Use the bundled JDK (preferable), or set `ES_JAVA_HOME`. `JAVA_HOME` will be
 ignored.
 ====
-//end::notable-breaking-changes[]
diff --git a/docs/reference/migration/migrate_8_0/transform.asciidoc b/docs/reference/migration/migrate_8_0/transform.asciidoc
@@ -2,10 +2,6 @@
 [[breaking_80_transform_changes]]
 ==== Transform changes
 
-//NOTE: The notable-breaking-changes tagged regions are re-used in the
-//Installation and Upgrade Guide
-
-//tag::notable-breaking-changes[]
 .{transforms-cap} created in 7.4 or earlier versions must be upgraded.
 [%collapsible]
 ====
@@ -18,4 +14,3 @@ that is no longer supported.
 Use the {ref}/upgrade-transforms.html[upgrade {transforms} API] to fix your
 {transforms}. This upgrade does not affect the source or destination indices.
 ====
-// end::notable-breaking-changes[]
diff --git a/docs/reference/migration/migrate_8_1.asciidoc b/docs/reference/migration/migrate_8_1.asciidoc
@@ -19,9 +19,6 @@ and prevent them from operating normally.
 Before upgrading to 8.1, review these changes and take the described steps
 to mitigate the impact.
 
-// NOTE: The notable-breaking-changes tagged regions are re-used in the
-// Installation and Upgrade Guide
-// tag::notable-breaking-changes[]
 [discrete]
 [[breaking_81_rest_api_changes]]
 ==== REST API changes
@@ -40,7 +37,6 @@ still retrieve original, unnormalized geometry objects from `_source`.
 If your application requires unnormalized geometry objects, retrieve them from
 `_source` rather than using the `fields` parameter.
 ====
-// end::notable-breaking-changes[]
 
 
 [discrete]
@@ -56,7 +52,6 @@ after upgrading to 8.1.
 To find out if you are using any deprecated functionality,
 enable <<deprecation-logging, deprecation logging>>.
 
-// tag::notable-breaking-changes[]
 [discrete]
 [[deprecations_81_cluster_and_node_setting]]
 ==== Cluster and node setting deprecations
@@ -94,7 +89,6 @@ actions.
 Ensure that bulk actions are well-formed JSON objects containing a single entry
 with the correct key.
 ====
-// end::notable-breaking-changes[]
 
 [[deprecate_index_include_frozen_request_parameter_in_sql_api]]
 .Deprecate `index_include_frozen` request parameter in `_sql` API