[DOCS] Rebrand breaking changes as the Migration guide (#66569)

* [DOCS] Rebrand breaking changes as the Migration guide

* Edits

* Fix version reference

* Fixed typo

* Added subsection intros & added info about the deprecation policy

docs/reference/migration/index.asciidoc

@@ -1,25 +1,44 @@
 [[breaking-changes]]
-= Breaking changes
+= Migration guide
 
 [partintro]
 --
-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>>.
+This section describes the breaking changes and deprecations introduced in this release 
+and previous minor versions. 
 
+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>>.
 
-* <<breaking-changes-7.10,Breaking changes in 7.10>>
-* <<breaking-changes-7.9,Breaking changes in 7.9>>
-* <<breaking-changes-7.8,Breaking changes in 7.8>>
-* <<breaking-changes-7.7,Breaking changes in 7.7>>
-* <<breaking-changes-7.6,Breaking changes in 7.6>>
-* <<breaking-changes-7.5,Breaking changes in 7.5>>
-* <<breaking-changes-7.4,Breaking changes in 7.4>>
-* <<breaking-changes-7.3,Breaking changes in 7.3>>
-* <<breaking-changes-7.2,Breaking changes in 7.2>>
-* <<breaking-changes-7.1,Breaking changes in 7.1>>
-* <<breaking-changes-7.0,Breaking changes in 7.0>>
+* <<breaking-changes-7.10,Migrating to 7.10>>
+* <<breaking-changes-7.9,Migrating to 7.9>>
+* <<breaking-changes-7.8,Migrating to 7.8>>
+* <<breaking-changes-7.7,Migrating to 7.7>>
+* <<breaking-changes-7.6,Migrating to 7.6>>
+* <<breaking-changes-7.5,Migrating to 7.5>>
+* <<breaking-changes-7.4,Migrating to 7.4>>
+* <<breaking-changes-7.3,Migrating to 7.3>>
+* <<breaking-changes-7.2,Migrating to 7.2>>
+* <<breaking-changes-7.1,Migrating to 7.1>>
+* <<breaking-changes-7.0,Migrating to 7.0>>
 
 --
 

docs/reference/migration/migrate_7_10.asciidoc

@@ -1,5 +1,5 @@
-[[breaking-changes-7.10]]
-== Breaking changes in 7.10
+[[migrating-7.10]]
+== Migrating to 7.10
 ++++
 <titleabbrev>7.10</titleabbrev>
 ++++
@@ -15,11 +15,30 @@ See also <<release-highlights>> and <<es-release-notes>>.
 //NOTE: The notable-breaking-changes tagged regions are re-used in the
 //Installation and Upgrade Guide
 
+
+
+[discrete]
+[[breaking-changes-7.10]]
+=== Breaking changes
+
+The following changes in {es} 7.10 might affect your applications
+and prevent them from operating normally.
+Before upgrading to 7.10, 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>>.
+
+
 //tag::notable-breaking-changes[]
 
 [discrete]
 [[breaking_710_security_changes]]
-=== Authentication changes
+==== Authentication changes
 
 [[api-keys-require-name-property]]
 .API keys now require a `name` property.
@@ -43,9 +62,85 @@ The `name` property is now required to create or grant an API key.
 To avoid errors, specify the `name` property when creating or granting API keys.
 ====
 
+[discrete]
+[[breaking_710_java_changes]]
+==== Java changes
+
+[[supplier-searchlookup-arg]]
+.The `MappedFieldType#fielddataBuilder` method now accepts a `Supplier<SearchLookup>` argument.
+[%collapsible]
+====
+*Details* +
+To support future feature development, the existing
+`MappedFieldType#fielddataBuilder` method now accepts a new
+`Supplier<SearchLookup>` argument.
+
+*Impact* +
+If you develop or maintain a mapper plugin, update your implementation of the
+`MappedFieldType#fielddataBuilder` method to accommodate the new signature.
+====
+
+[discrete]
+[[breaking_710_networking_changes]]
+==== Networking changes
+
+[keep-idle-and-keep-internal-limits]
+.The `*.tcp.keep_idle` and `*.tcp.keep_interval` settings are now limited to `300` seconds.
+[%collapsible]
+====
+*Details* +
+The `{network,transport,http}.tcp.keep_idle` and
+`{network,transport,http}.tcp.keep_interval` settings now have a maximum
+value of `300` seconds, equivalent to 5 minutes.
+
+*Impact* +
+If specified, ensure the `{network,transport,http}.tcp.keep_idle` and
+`{network,transport,http}.tcp.keep_interval` settings do not exceed `300`
+seconds. Setting `{network,transport,http}.tcp.keep_idle` or
+`{network,transport,http}.tcp.keep_interval` to a value greater than `300`
+seconds in `elasticsearch.yml` will result in an error on startup.
+====
+
+[discrete]
+[[breaking_710_search_changes]]
+==== Search changes
+
+[[max-doc-value-field-search-limits]]
+.The `index.max_docvalue_fields_search` setting now limits doc value fields returned by `inner_hits` or the `top_hits` aggregation.
+[%collapsible]
+====
+*Details* +
+The `index.max_docvalue_fields_search` setting limits the number of doc value
+fields retrieved by a search. Previously, this setting applied only to doc value
+fields returned by the `docvalue_fields` parameter in a top-level search. The
+setting now also applies to doc value fields returned by an `inner_hits` section
+or `top_hits` aggregation.
+
+*Impact* +
+If you use `inner_hits` or the `top_hits` aggregation, ensure
+`index.max_docvalue_fields_search` is configured correctly for your use case.
+====
+
+//end::notable-breaking-changes[]
+
+[discrete]
+[[deprecated-7.10]]
+=== Deprecations
+
+The following functionality has been deprecated in {es} 7.10
+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 7.10.
+
+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>>.
+
 [discrete]
 [[breaking_710_indices_changes]]
-=== Indices changes
+==== Indices deprecations
 
 [[bc-deprecate-rest-api-access-to-system-indices]]
 .REST API access to system indices is deprecated.
@@ -80,28 +175,9 @@ To avoid deprecation warnings, do not use unsupported REST APIs to access system
 indices.
 ====
 
-
-[discrete]
-[[breaking_710_java_changes]]
-=== Java changes
-
-[[supplier-searchlookup-arg]]
-.The `MappedFieldType#fielddataBuilder` method now accepts a `Supplier<SearchLookup>` argument.
-[%collapsible]
-====
-*Details* +
-To support future feature development, the existing
-`MappedFieldType#fielddataBuilder` method now accepts a new
-`Supplier<SearchLookup>` argument.
- 
-*Impact* +
-If you develop or maintain a mapper plugin, update your implementation of the
-`MappedFieldType#fielddataBuilder` method to accommodate the new signature.
-====
-
 [discrete]
 [[breaking_710_ml_changes]]
-=== Machine learning changes
+==== Machine learning deprecations
 
 [[ml-allow-no-deprecations]]
 .The `allow_no_jobs` and `allow_no_datafeeds` API parameters are deprecated.
@@ -120,7 +196,7 @@ To avoid deprecation warnings, use the `allow_no_match` parameter.
 
 [discrete]
 [[breaking_710_mapping_changes]]
-=== Mapping changes
+==== Mapping deprecations
 
 [[mapping-boosts]]
 .The `boost` parameter on field mappings has been deprecated.
@@ -137,50 +213,9 @@ The `boost` setting should be removed from templates and mappings. Use boosts
 directly on queries instead.
 ====
 
-[discrete]
-[[breaking_710_networking_changes]]
-=== Networking changes
-
-[keep-idle-and-keep-internal-limits]
-.The `*.tcp.keep_idle` and `*.tcp.keep_interval` settings are now limited to `300` seconds.
-[%collapsible]
-====
-*Details* +
-The `{network,transport,http}.tcp.keep_idle` and
-`{network,transport,http}.tcp.keep_interval` settings now have a maximum
-value of `300` seconds, equivalent to 5 minutes.
-
-*Impact* +
-If specified, ensure the `{network,transport,http}.tcp.keep_idle` and
-`{network,transport,http}.tcp.keep_interval` settings do not exceed `300`
-seconds. Setting `{network,transport,http}.tcp.keep_idle` or
-`{network,transport,http}.tcp.keep_interval` to a value greater than `300`
-seconds in `elasticsearch.yml` will result in an error on startup.
-====
-
-[discrete]
-[[breaking_710_search_changes]]
-=== Search changes
-
-[[max-doc-value-field-search-limits]]
-.The `index.max_docvalue_fields_search` setting now limits doc value fields returned by `inner_hits` or the `top_hits` aggregation.
-[%collapsible]
-====
-*Details* +
-The `index.max_docvalue_fields_search` setting limits the number of doc value
-fields retrieved by a search. Previously, this setting applied only to doc value
-fields returned by the `docvalue_fields` parameter in a top-level search. The
-setting now also applies to doc value fields returned by an `inner_hits` section
-or `top_hits` aggregation.
-
-*Impact* +
-If you use `inner_hits` or the `top_hits` aggregation, ensure
-`index.max_docvalue_fields_search` is configured correctly for your use case.
-====
-
 [discrete]
 [[breaking_710_snapshot_restore_changes]]
-=== Snapshot and restore changes
+==== Snapshot and restore deprecations
 
 [[respository-stats-api-deprecated]]
 .The repository stats API has been deprecated.
@@ -196,4 +231,3 @@ removed in 8.0.0.
 Use the {ref}/repositories-metering-apis.html[repositories metering APIs].
 Discontinue use of the repository stats API.
 ====
-//end::notable-breaking-changes[]