Reorganize 5.0 release notes (mongodb#524)

---------

Co-authored-by: Jeff Yemin <[email protected]>

source/upgrade.txt

@@ -289,18 +289,18 @@ This driver version introduces the following breaking changes:
   code using these methods must be recompiled. This change does not require any
   changes to source code.
 
-- Removes the following methods and types related to the 
-  `StreamFactory
-  <https://mongodb.github.io/mongo-java-driver/4.11/apidocs/mongodb-driver-core/com/mongodb/connection/StreamFactory.html>`__
-
-- Removes the following methods and types related to the 
+- Removes the following methods and types related to the
   `Stream
   <https://mongodb.github.io/mongo-java-driver/4.11/apidocs/mongodb-driver-core/com/mongodb/connection/Stream.html>`__
   interface:
 
-  - ``streamFactoryFactory()`` method from ``MongoClientSettings.Builder``
-  - ``getStreamFactoryFactory()`` method from ``MongoClientSettings``
-  - ``NettyStreamFactoryFactory`` class
+  - ``streamFactoryFactory()`` method from ``MongoClientSettings.Builder``.
+    Use the ``MongoClientSettings.Builder.transportSettings()`` method instead.
+  - ``getStreamFactoryFactory()`` method from ``MongoClientSettings``.
+    Use the ``MongoClientSettings.getTransportSettings()`` method instead.
+  - ``NettyStreamFactoryFactory`` class.
+    Use the ``NettyTransportSettings``, creatable by ``TransportSettings.nettyBuilder()``
+    and applied through ``MongoClientSettings.Builder.transportSettings()``.
   - ``NettyStreamFactory`` class
   - ``AsynchronousSocketChannelStreamFactory`` class
   - ``AsynchronousSocketChannelStreamFactoryFactory`` class

source/whats-new.txt

@@ -40,37 +40,65 @@ Learn what's new in:
 What's New in 5.0
 -----------------
 
-.. warning:: Breaking Changes in v5.0
+.. warning:: Breaking changes in this release
 
   This driver version introduces breaking changes. For a list of these changes, see 
   the :ref:`Version 5.0 Breaking Changes section <java-breaking-changes-v5.0>` in the 
   Upgrade guide.
 
-The 5.0 driver release introduces the following features:
+.. warning:: Deprecations in this release
+
+   To avoid breaking changes in future major releases of the driver,
+   replace any application code that depends on deprecated program elements.
+
+This section includes the following information:
+
+- :ref:`java-deprecations-5.0`
+- :ref:`java-behavioral-changes-5.0`
+- :ref:`java-new-features-5.0`
+
+.. _java-deprecations-5.0:
+
+Deprecations in 5.0
+~~~~~~~~~~~~~~~~~~~
+
+- The ``org.mongodb.scala.Observable.completeWithUnit()`` method is deprecated.
+  This method is not useful anymore because
+  the driver now exposes ``org.mongodb.scala.Observable[Unit]``
+  instead of ``org.mongodb.scala.Observable[Void]``.
+  This relates to a :ref:`breaking change about Observables in this release
+  <java-breaking-changes-v5.0-observables>`.
+
+.. _java-behavioral-changes-5.0:
+
+Behavioral changes in 5.0
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - The ``getElapsedTime()`` method on ``com.mongodb.event.ConnectionReadyEvent``
   includes the time taken to deliver the ``ConnectionCreatedEvent``. That is,
   the time returned includes the duration of the
   ``com.mongodb.event.ConnectionPoolListener.connectionCreated()`` method.
-  
+
   The ``getElapsedTime()`` methods on
   ``com.mongodb.event.ConnectionCheckedOutFailedEvent`` and
   ``com.mongodb.event.ConnectionCheckedOutEvent`` include the time taken to
   deliver the ``com.mongodb.event.ConnectionCheckOutStartedEvent``. That is, the
   time returned includes the duration of the
   ``com.mongodb.eventConnectionPoolListener.connectionCheckOutStarted()`` method.
 
-- The ``org.mongodb.scala.Observable.completeWithUnit()`` method is deprecated.
-  This relates to a :ref:`breaking change about Observables in this version
-  <java-breaking-changes-v5.0-observables>`.
+.. _java-new-features-5.0:
 
-- Changes to the ``ConnectionId`` class. To learn more, see the
-  :ref:`Version 5.0 Breaking Changes <java-breaking-changes-v5.0>`.
-
-- Changes to the ``com.mongodb.client.MongoDatabase.listCollectionNames()``
-  methods. The return type is now a
-  ``com.mongodb.client.ListCollectionNamesIterable`` type, while previously it
-  was a ``MongoIterable<String>``. This change allows the return value to be
+New features in 5.0
+~~~~~~~~~~~~~~~~~~~
+
+The 5.0 driver release introduces the following features:
+
+- Adds support for the ``authorizedCollection`` option of
+  the ``listCollections`` command. This was done by changing the
+  ``com.mongodb.client.MongoDatabase.listCollectionNames()`` methods.
+  The return type is now ``com.mongodb.client.ListCollectionNamesIterable``,
+  while previously it was a ``MongoIterable<String>``.
+  This change allows the return value to be
   configured using the ``ListCollectionNamesIterable.authorizedCollections()``
   method and specifying the ``authorizedCollections`` option. Equivalent changes
   were made to following classes and interfaces: