Add info on backward compatibility; add anchor for draining queue

Fixes #9796

docs/static/breaking-changes.asciidoc

@@ -1,11 +1,27 @@
 [[breaking-changes]]
 == Breaking Changes
 
-This section discusses the changes that you need to be aware of when migrating to Logstash 6.0.0 from the previous major releases.
+We strive to maintain backward compatibility between minor versions (6.x to 6.y,
+for example) so that you can upgrade without changing any configuration files.
+Breaking changes are usually introduced only between major versions (such as 5.x
+to 6.y). On occasion, we are forced to break compatibility within a given major release
+to ensure correctness of operation.
+
+This section covers the changes that you need to be aware of when migrating to
+Logstash 6.0.0 and later.
+
+NOTE: Migrating directly between non-consecutive major versions (1.x to
+6.x) is not recommended.
+
+See these topics for a description of breaking changes:
+
+* <<breaking-pq>>
+* <<breaking-6.0>>
 
 See also <<releasenotes>>. 
 
 [float]
+[[breaking-pq]]
 === Breaking change across PQ versions prior to Logstash 6.3.0
 
 If you are upgrading from Logstash 6.2.x or any earlier version (including 5.x)
@@ -13,38 +29,44 @@ and have the persistent queue enabled, we strongly recommend that you drain or
 delete the persistent queue before you upgrade. See <<upgrading-logstash-pqs>>
 for information and instructions.
 
-We are working to resolve issues with data incompatibilities in our 6.3.0
-release so that additional steps won't be required for future upgrades. 
+We are working to resolve issues with data incompatibilities so that additional
+steps won't be required for future upgrades.  
 
 [float]
-=== Changes in Logstash Core
+[[breaking-6.0]]
+=== Breaking changes in 6.0
+
+Here are the breaking changes for 6.0.
+
+[float]
+==== Changes in Logstash Core
 
 These changes can impact any instance of Logstash and are plugin agnostic, but only if you are using the features that are impacted.
 
 [float]
-==== Application Settings
+===== Application Settings
 
 * The setting `config.reload.interval` has been changed to use time value strings such as `5m`, `10s` etc.
   Previously, users had to convert this to a millisecond time value themselves.
 
 [float]
-==== RPM/Deb package changes
+===== RPM/Deb package changes
 
 * For `rpm` and `deb` release artifacts, config files that match the `*.conf` glob pattern must be in the conf.d folder,
   or the files will not be loaded.
 
 [float]
-==== Command Line Interface behavior
+===== Command Line Interface behavior
 
 * The `-e` and `-f` CLI options are now mutually exclusive. This also applies to the corresponding long form options `config.string` and
   `path.config`. This means any configurations  provided via `-e` will no longer be appended to the configurations provided via `-f`.
 * Configurations provided with `-f` or `config.path` will not be appended with `stdin` input and `stdout` output automatically.
 
 [float]
-=== Plugin Changes
+==== Plugin Changes
 
 [float]
-==== Elasticsearch output changes
+===== Elasticsearch output changes
 
 * The default `document_type` has changed from `logs` to `doc` for consistency with Beats.
   Furthermore, users are advised that Elasticsearch 6.0 deprecates doctypes, and 7.0 will remove them. 
@@ -54,7 +76,7 @@ These changes can impact any instance of Logstash and are plugin agnostic, but o
  The new mapping template has been updated to reflect that. If you are using a custom mapping template you may need to update it to reflect that.
 
 [float]
-==== Kafka input changes
+===== Kafka input changes
 
 * Upgraded Kafka client support to v0.11.0.0, which only supports Kafka brokers v0.10.x or later.
 ** Please refer to <<plugins-inputs-kafka,Kafka input plugin>> documentation for information about Kafka compatibility with Logstash.
@@ -63,21 +85,21 @@ These changes can impact any instance of Logstash and are plugin agnostic, but o
 * The `ssl` option is now obsolete.
 
 [float]
-==== Kafka output changes
+===== Kafka output changes
 
 * Upgraded Kafka client support to v0.11.0.0, which only supports Kafka brokers v0.10.x or later.
 ** Please refer to <<plugins-outputs-kafka,Kafka output plugin>> documentation for information about Kafka compatibility with Logstash.
 * The options `block_on_buffer_full`, `ssl`, and `timeout_ms` are now obsolete.
 
 [float]
-==== Beats input changes
+===== Beats input changes
 
 * Logstash will no longer start when <<plugins-codecs-multiline,Multiline codec plugin>> is used with the Beats input plugin.
 ** It is recommended to use the multiline support in Filebeat as a replacement - see https://www.elastic.co/guide/en/beats/filebeat/current/multiline-examples.html[configuration options available in Filebeat] for details.
 * The options `congestion_threshold` and `target_field_for_codec` are now obsolete.
 
 [float]
-==== List of plugins bundled with Logstash
+===== List of plugins bundled with Logstash
 
 The following plugins were removed from the 6.0 default bundle based on usage data. You can still install these plugins manually:
 

docs/static/upgrading.asciidoc

@@ -127,6 +127,7 @@ break that compatibility in version 6.3.0 to ensure correctness of operation.
 For more technical details on this issue, please check our tracking github issue
 for this matter, https://github.com/elastic/logstash/issues/9494[#9494].
 
+[[drain-pq]]
 ==== Drain the Persistent Queue
 
 If you are upgrading from Logstash 6.2.x or an earlier version and use the persistent
@@ -144,5 +145,5 @@ When the queue is empty:
 . Complete the upgrade.
 . Restart Logstash.
 
-We are working to resolve issues with data incompatibilities in our 6.3.0
-release so that these steps won’t be required for future upgrades.
+We are working to resolve issues with data incompatibilities so that these steps
+won’t be required for future upgrades.