Add 3.0 migration guide (#4927)

2 files changed, 48 insertions, 0 deletions

diff --git a/doc/release/migration_guide_from_2.x_to_3.0.rst b/doc/release/migration_guide_from_2.x_to_3.0.rst
new file mode 100644
index 00000000..d02ac76c
--- /dev/null
+++ b/doc/release/migration_guide_from_2.x_to_3.0.rst
@@ -0,0 +1,44 @@
+:orphan:
+
+*****************************
+Preparing for the 3.0 release
+*****************************
+
+.. note::
+   Much of the work leading to the NetworkX 3.0 release will be included
+   in the NetworkX 2.6 and 2.7 releases.  For example, we are changing our
+   default dependencies in the 2.6 release and we are deprecating a lot
+   of old code in the 2.6 and 2.7 releases.  This guide will discuss this
+   ongoing work and will help you understand what changes you can make now
+   to minimize the disruption caused by the move to 3.0.
+
+This is a guide for people moving from NetworkX 2.X to NetworkX 3.0
+
+Any issues with these can be discussed on the `mailing list
+<https://groups.google.com/forum/#!forum/networkx-discuss>`_.
+
+The focus of 3.0 release is on addressing years of technical debt, modernizing our codebase,
+improving performance, and making it easier to contribute.
+We plan to release 2.7 near the end of summer and 3.0 near the end of the year.
+
+Default dependencies
+--------------------
+
+We no longer depend on the "decorator" library.
+
+NumPy, SciPy, Matplotlib, and Pandas are now default dependencies due to their
+central position in the scientific Python ecosystem and the fact that they
+provide self-contained, easy to install wheels for pip.
+While we've made these core libraries of the scientific Python ecosystem default dependencies,
+much of NetworkX still works without these libraries and we expect that to continue.
+Be assured that we test NetworkX with and without the dependencies,
+so if you do **not** use functions that depend on external libraries
+you can install NetworkX using pip with the `--no-deps` flag::
+
+    $ pip install networkx --no-deps
+
+Deprecated code
+---------------
+
+The 2.6 release deprecates over 30 functions.
+See :ref:`NetworkX 2.6`.
diff --git a/doc/release/release_dev.rst b/doc/release/release_dev.rst
index 07db238b..46a5c08e 100644
--- a/doc/release/release_dev.rst
+++ b/doc/release/release_dev.rst
@@ -1,3 +1,5 @@
+.. _NetworkX 2.6:
+
 Next Release
 ============
 
@@ -5,6 +7,8 @@ Release date: TBD
 
 Supports Python 3.7, 3.8, and 3.9.
 
+See :doc:`migration_guide_from_2.x_to_3.0`.
+
 NetworkX is a Python package for the creation, manipulation, and study of the
 structure, dynamics, and functions of complex networks.