Rebranded breaking changes as the migration guide (#67496)

* Rebranded breaking changes as the migration guide

* Fixed heading level

docs/reference/migration/index.asciidoc

@@ -7,7 +7,33 @@ This section discusses the changes that you need to be aware of to migrate
 your application to {version}. For more information about what's new in this
 release, see the <<release-highlights>> and <<es-release-notes>>.
 
-For information about how to upgrade your cluster, see <<setup-upgrade>>.
+As {es} introduces new features and improves existing ones,
+the changes sometimes make older settings, APIs, and parameters obsolete.
+The obsolete functionality is typically deprecated in a minor release and
+removed in the subsequent major release.
+This enables applications to continue working unchanged
+across most minor version upgrades.
+Breaking changes introduced in minor releases are
+generally limited to critical security fixes
+and bug fixes that correct unintended behavior.
+
+To get the most out of {es} and facilitate future upgrades,
+we strongly encourage migrating
+away from using deprecated functionality as soon as possible.
+
+To give you insight into what deprecated features you're using, {es}:
+
+- Returns a `Warn` HTTP header whenever you
+submit a request that uses deprecated functionality.
+- <<deprecation-logging, Logs deprecation warnings>> when
+deprecated functionality is used.
+- <<migration-api-deprecation, Provides a deprecation info API>>
+that scans a cluster's configuration
+and mappings for deprecated functionality.
+
+For more information about {minor-version},
+see the <<release-highlights>> and <<es-release-notes>>.
+For information about how to upgrade your cluster, see <<setup-upgrade>>.	For information about how to upgrade your cluster, see <<setup-upgrade>>.
 
 * <<breaking-changes-8.0,Breaking changes in 8.0>>
 

docs/reference/migration/migrate_8_0.asciidoc

@@ -1,5 +1,5 @@
-[[breaking-changes-8.0]]
-== Breaking changes in 8.0
+[[migrating-8.0]]
+== Migrating to 8.0
 ++++
 <titleabbrev>8.0</titleabbrev>
 ++++
@@ -35,6 +35,22 @@ coming[8.0.0]
 * <<breaking_80_threadpool_changes>>
 * <<breaking_80_transport_changes>>
 
+[discrete]
+[[breaking-changes-8.0]]
+=== Breaking changes
+
+The following changes in {es} 8.0 might affect your applications
+and prevent them from operating normally.
+Before upgrading to 8.0, review these changes and take the described steps
+to mitigate the impact.
+
+NOTE: Breaking changes introduced in minor versions are
+normally limited to security and bug fixes.
+Significant changes in behavior are deprecated in a minor release and
+the old behavior is supported until the next major release.
+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
 
@@ -93,3 +109,20 @@ include::migrate_8_0/snapshots.asciidoc[]
 include::migrate_8_0/threadpool.asciidoc[]
 include::migrate_8_0/transport.asciidoc[]
 include::migrate_8_0/migrate_to_java_time.asciidoc[]
+
+////
+[discrete]
+[[deprecated-8.0]]
+=== Deprecations
+
+The following functionality has been deprecated in {es} 8.0
+and will be removed in 8.0
+While this won't have an immediate impact on your applications,
+we strongly encourage you take the described steps to update your code
+after upgrading to 8.0.
+
+NOTE: Significant changes in behavior are deprecated in a minor release and
+the old behavior is supported until the next major release.
+To find out if you are using any deprecated functionality,
+enable <<deprecation-logging, deprecation logging>>.
+////

docs/reference/migration/migrate_8_0/aggregations.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_aggregations_changes]]
-=== Aggregations changes
+==== Aggregations changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide
@@ -20,4 +20,4 @@ Use unique values in the `percents` parameter of the `percentiles` aggregation.
 Requests containing duplicate values in the `percents` parameter will return
 an error.
 ====
-// end::notable-breaking-changes[]
+// end::notable-breaking-changes[]

docs/reference/migration/migrate_8_0/allocation.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_allocation_changes]]
-=== Allocation changes
+==== Allocation changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide

docs/reference/migration/migrate_8_0/analysis.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_analysis_changes]]
-=== Analysis changes
+==== Analysis changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide
@@ -15,7 +15,7 @@
 ====
 *Details* +
 The `nGram` and `edgeNGram` token filter names that have been deprecated since
-version 6.4 have been removed. Both token filters can only be used by their 
+version 6.4 have been removed. Both token filters can only be used by their
 alternative names `ngram` and `edge_ngram` since version 7.0.
 
 *Impact* +
@@ -34,6 +34,6 @@ emit a deprecation warning. The tokenizer name should be changed to the fully eq
 `ngram` or `edge_ngram` names for new indices and in index templates.
 
 *Impact* +
-Use the `ngram` and `edge_ngram` tokenizers. Requests to create new indices 
+Use the `ngram` and `edge_ngram` tokenizers. Requests to create new indices
 using the `nGram` and `edgeNGram` tokenizer names will return an error.
 ====

docs/reference/migration/migrate_8_0/api.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_api_changes]]
-=== REST API changes
+==== REST API changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide

docs/reference/migration/migrate_8_0/breaker.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_breaker_changes]]
-=== Circuit breaker changes
+==== Circuit breaker changes
 
 //tag::notable-breaking-changes[]
 .The `in_flight_requests` stat has been renamed `inflight_requests` in logs and diagnostic APIs.

docs/reference/migration/migrate_8_0/cluster.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_cluster_changes]]
-=== Cluster changes
+==== Cluster changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide

docs/reference/migration/migrate_8_0/discovery.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_discovery_changes]]
-=== Discovery changes
+==== Discovery changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide

docs/reference/migration/migrate_8_0/http.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_http_changes]]
-=== HTTP changes
+==== HTTP changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide

docs/reference/migration/migrate_8_0/ilm.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_ilm_changes]]
-=== {ilm-cap} changes
+==== {ilm-cap} changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide
@@ -40,4 +40,4 @@ renamed to `ilm` to match the package rename inside the {es} code.
 *Impact* +
 Update your workflow and applications to use the `ilm` package in place of
 `indexlifecycle`.
-====
+====

docs/reference/migration/migrate_8_0/indices.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_indices_changes]]
-=== Indices changes
+==== Indices changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide

docs/reference/migration/migrate_8_0/java.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_java_changes]]
-=== Java API changes
+==== Java API changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide

docs/reference/migration/migrate_8_0/mappings.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_mappings_changes]]
-=== Mapping changes
+==== Mapping changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide

docs/reference/migration/migrate_8_0/migrate_to_java_time.asciidoc

@@ -8,7 +8,7 @@ if your cluster is impacted and, if so, prepare for the upgrade.
 
 [discrete]
 [[java-time-convert-date-formats]]
-=== Convert date formats
+==== Convert date formats
 
 To upgrade to {es} 8, you'll need to convert any joda-time date formats
 to their java-time equivalents.
@@ -315,4 +315,3 @@ POST /_aliases
 }
 --------------------------------------------------
 // TEST[continued]
-

docs/reference/migration/migrate_8_0/network.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_network_changes]]
-=== Network changes
+==== Network changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide
@@ -21,4 +21,4 @@ timeout for client connections. Discontinue use of the
 `network.tcp.connect_timeout` setting. Specifying the
 `network.tcp.connect_timeout` setting in `elasticsearch.yml` will result in an
 error on startup.
-====
+====

docs/reference/migration/migrate_8_0/node.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_node_changes]]
-=== Node changes
+==== Node changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide
@@ -28,7 +28,7 @@ setting in `elasticsearch.yml` will result in an error on startup.
 Each node's data is now stored directly in the data directory set by the
 `path.data` setting, rather than in `${path.data}/nodes/0`, because the removal
 of the `node.max_local_storage_nodes` setting means that nodes may no longer
-share a data path. 
+share a data path.
 
 *Impact* +
 At startup, {es} will automatically migrate the data path to the new layout.
@@ -60,4 +60,4 @@ open or closed, at startup time.
 *Impact* +
 Reindex closed indices created in {es} 6.x or before with {es} 7.x if they need
 to be carried forward to {es} 8.x.
-====
+====

docs/reference/migration/migrate_8_0/packaging.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_packaging_changes]]
-=== Packaging changes
+==== Packaging changes
 
 //tag::notable-breaking-changes[]
 .Java 11 is required.

docs/reference/migration/migrate_8_0/reindex.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_reindex_changes]]
-=== Reindex changes
+==== Reindex changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide
@@ -51,4 +51,4 @@ Similarly, the `size` parameter has been renamed to `max_docs` for
 *Impact* +
 Use the replacement parameters. Requests containing the `size` parameter will
 return an error.
-====
+====

docs/reference/migration/migrate_8_0/rollup.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_rollup_changes]]
-=== Rollup changes
+==== Rollup changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide
@@ -50,4 +50,4 @@ The request itself may have started the job, or it was previously running and so
 the request had no effect.
 ====
 
-endif::[]
+endif::[]

docs/reference/migration/migrate_8_0/search.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_search_changes]]
-=== Search Changes
+==== Search Changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide
@@ -164,7 +164,7 @@ return an error.
 *Details* +
 Range queries on date fields used to misinterpret small numbers (e.g. four digits like 1000)
 as a year when no additional format was set, but would interpret other numeric values as
-milliseconds since epoch. We now treat all numeric values in absence of a specific `format` 
+milliseconds since epoch. We now treat all numeric values in absence of a specific `format`
 parameter as milliseconds since epoch. If you want to query for years instead, with a missing
 `format` you now need to quote the input value (e.g. "1984").
 

docs/reference/migration/migrate_8_0/security.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_security_changes]]
-=== Security changes
+==== Security changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide

docs/reference/migration/migrate_8_0/settings.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_settings_changes]]
-=== Settings changes
+==== Settings changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide

docs/reference/migration/migrate_8_0/snapshots.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_snapshots_changes]]
-=== Snapshot and restore changes
+==== Snapshot and restore changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide

docs/reference/migration/migrate_8_0/threadpool.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_threadpool_changes]]
-=== Thread pool changes
+==== Thread pool changes
 
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide
@@ -18,4 +18,4 @@ The `search` and `search_throttled` thread pools have the `fixed` type now.
 
 *Impact* +
 No action needed.
-====
+====

docs/reference/migration/migrate_8_0/transport.asciidoc

@@ -1,6 +1,6 @@
 [discrete]
 [[breaking_80_transport_changes]]
-=== Transport changes
+==== Transport changes
 
 //tag::notable-breaking-changes[]
 .Several `transport` settings have been replaced.