PYTHON-2388 Begin PyMongo 4.0 migration guide (#540)

Author: ShaneHarvey

doc/changelog.rst

@@ -4,9 +4,17 @@ Changelog
 Changes in Version 4.0
 ----------------------
 
+.. warning:: PyMongo 4.0 drops support for Python 2.7, 3.4, and 3.5.
+
+PyMongo 4.0 brings a number of improvements as well as some backward breaking
+changes. For example, all APIs deprecated in PyMongo 3.X have been removed.
+Be sure to read the changes listed below and the :doc:`migrate-to-pymongo4`
+before upgrading from PyMongo 3.x.
+
 Breaking Changes in 4.0
-```````````````````````
+.......................
 
+- Removed support for Python 2.7, 3.4, and 3.5. Python 3.6+ is now required.
 - Removed :mod:`~pymongo.thread_util`.
 
 Issues Resolved

doc/index.rst

@@ -31,6 +31,9 @@ everything you need to know to use **PyMongo**.
 :doc:`faq`
   Some questions that come up often.
 
+:doc:`migrate-to-pymongo4`
+  A PyMongo 3.x to 4.x migration guide.
+
 :doc:`migrate-to-pymongo3`
   A PyMongo 2.x to 3.x migration guide.
 
@@ -119,5 +122,6 @@ Indices and tables
    contributors
    changelog
    python3
+   migrate-to-pymongo4
    migrate-to-pymongo3
    developer/index

doc/migrate-to-pymongo4.rst

@@ -0,0 +1,53 @@
+PyMongo 4 Migration Guide
+=========================
+
+.. contents::
+
+.. testsetup::
+
+  from pymongo import MongoClient, ReadPreference
+  client = MongoClient()
+  collection = client.my_database.my_collection
+
+PyMongo 4.0 brings a number of improvements as well as some backward breaking
+changes. This guide provides a roadmap for migrating an existing application
+from PyMongo 3.x to 4.x or writing libraries that will work with both
+PyMongo 3.x and 4.x.
+
+PyMongo 3
+---------
+
+The first step in any successful migration involves upgrading to, or
+requiring, at least that latest version of PyMongo 3.x. If your project has a
+requirements.txt file, add the line "pymongo >= 3.12, < 4.0" until you have
+completely migrated to PyMongo 4. Most of the key new methods and options from
+PyMongo 4.0 are backported in PyMongo 3.12 making migration much easier.
+
+.. note:: Users of PyMongo 2.X who wish to upgrade to 4.x must first upgrade
+   to PyMongo 3.x by following the :doc:`migrate-to-pymongo3`.
+
+Python 3.6+
+-----------
+
+PyMongo 4.0 drops support for Python 2.7, 3.4, and 3.5. Users who wish to
+upgrade to 4.x must first upgrade to Python 3.6+. Users upgrading from
+Python 2 should consult the :doc:`python3`.
+
+Enable Deprecation Warnings
+---------------------------
+
+:exc:`DeprecationWarning` is raised by most methods removed in PyMongo 4.0.
+Make sure you enable runtime warnings to see where deprecated functions and
+methods are being used in your application::
+
+  python -Wd <your application>
+
+Warnings can also be changed to errors::
+
+  python -Wd -Werror <your application>
+
+.. note:: Not all deprecated features raise :exc:`DeprecationWarning` when
+  used. See `Removed features with no migration path`_.
+
+Removed features with no migration path
+---------------------------------------