Add 'migrations' to the docs. Ref #368.

docs/index.rst

@@ -25,6 +25,7 @@ The documentation here includes a general :ref:`usage <using>` guide.
 
    using
    api
+   migration
    history
 
 

docs/migration.rst

@@ -0,0 +1,84 @@
+.. _migration:
+
+=================
+ Migration guide
+=================
+
+The following guide will help you migrate common ``pkg_resources``
+APIs to ``importlib_metadata``. ``importlib_metadata`` aims to
+replace the following ``pkg_resources`` APIs:
+
+* ``pkg_resources.iter_entry_points()``
+* ``pkg_resources.require()``
+* convenience functions
+* ``pkg_resources.find_distributions()``
+* ``pkg_resources.get_distribution()``
+
+Other functionality from ``pkg_resources`` is replaced by other
+packages such as
+`importlib_resources <https://pypi.org/project/importlib_resources>`_
+and `packaging <https://pypi.org/project/packaging>`_.
+
+
+pkg_resources.iter_entry_points()
+=================================
+
+``importlib_metadata`` provides :ref:`entry-points`.
+
+Compatibility note: entry points provided by importlib_metadata
+do not have the following implicit behaviors found in those
+from ``pkg_resources``:
+
+- Each EntryPoint is not automatically validated to match. To
+  ensure each one is validated, invoke any property on the
+  object (e.g. ``ep.name``).
+
+- When invoking ``EntryPoint.load()``, no checks are performed
+  to ensure the declared extras are installed. If this behavior
+  is desired/required, it is left to the user to perform the
+  check and install any dependencies. See
+  `importlib_metadata#368 <https://github.com/python/importlib_metadata/issues/368>`_
+  for more details.
+
+pkg_resources.require()
+=======================
+
+``importlib_metadata`` does not provide support for dynamically
+discovering or requiring distributions nor does it provide any
+support for managing the "working set". Furthermore,
+``importlib_metadata`` assumes that only one version of a given
+distribution is discoverable at any time (no support for multi-version
+installs). Any projects that require the above behavior needs to
+provide that behavior independently.
+
+``importlib_metadata`` does aim to resolve metadata concerns late
+such that any dynamic changes to package availability should be
+reflected immediately.
+
+Convenience functions
+=====================
+
+In addition to the support for direct access to ``Distribution``
+objects (below), ``importlib_metadata`` presents some top-level
+functions for easy access to the most common metadata:
+
+- :ref:`metadata` queries the metadata fields from the distribution.
+- :ref:`version` provides quick access to the distribution version.
+- :ref:`requirements` presents the requirements of the distribution.
+- :ref:`files` provides file-like access to the data blobs backing
+  the metadata.
+
+pkg_resources.find_distributions()
+==================================
+
+``importlib_metadata`` provides functionality
+similar to ``find_distributions()``. Both ``distributions(...)`` and
+``Distribution.discover(...)`` return an iterable of :ref:`distributions`
+matching the indicated parameters.
+
+pkg_resources.get_distribution()
+=================================
+
+Similar to ``distributions``, the ``distribution()`` function provides
+access to a single distribution by name.
+

docs/using.rst

@@ -243,6 +243,7 @@ Python packages or modules::
     >>> packages_distributions()
     {'importlib_metadata': ['importlib-metadata'], 'yaml': ['PyYAML'], 'jaraco': ['jaraco.classes', 'jaraco.functools'], ...}
 
+.. _distributions:
 
 Distributions
 =============