added cloning, pip -e, git clean, dev.txt

Pamela Wu · tacaswell · commit 19f7f4bfb828 · 2020-06-30T23:04:03.000-04:00
diff --git a/INSTALL.rst b/INSTALL.rst
@@ -91,17 +91,40 @@ Installing from source
 
 If you are interested in contributing to Matplotlib development,
 running the latest source code, or just like to build everything
-yourself, it is not difficult to build Matplotlib from source.  Grab
-the latest *tar.gz* release file from `the PyPI files page
-<https://pypi.org/project/matplotlib/>`_, or if you want to
-develop Matplotlib or just need the latest bugfixed version, grab the
-latest git version, and see :ref:`install-from-git`.
+yourself, it is not difficult to build Matplotlib from source.
+
+The easiest way to get the latest development version to start contributing
+is to go to the git `repository <https://github.com/matplotlib/matplotlib>`_
+and run: ::
+
+  git clone https://github.com/matplotlib/matplotlib.git
 
 Matplotlib can be installed from the source directory with a simple ::
 
-  python -m pip install .
+  pip install .
+
+If you're developing, it's better to do it in editable mode. The reason why
+is that there's a few artifacts for testing that are only properly referenced
+if installation is done this way. Also, editable mode allows your code changes
+to be instantly propagated to your library code without rebuilding (though
+you will have to restart your kernel): ::
+
+  pip install -e .
+
+Additionally, if you are planning on contributing, you may need additional
+dev dependencies: ::
+
+  pip install -r requirements/dev/dev.txt
 
-We provide a setup.cfg_ file which you can use to customize the build
+**Warning:** The following instructions in this section are for very custom
+installations of Matplotlib. Proceed with caution because these instructions
+may result in your build producing unexpected behavior and/or causing
+local testing to fail.
+
+If you would like to build from a tarball, grab the latest *tar.gz* release
+file from `the PyPI files page <https://pypi.org/project/matplotlib/>`_.
+
+We provide a `setup.cfg`_ file which you can use to customize the build
 process. For example, which default backend to use, whether some of the
 optional libraries that Matplotlib ships with are installed, and so on.  This
 file will be particularly useful to those packaging Matplotlib.
@@ -113,6 +136,9 @@ file will be particularly useful to those packaging Matplotlib.
 Dependencies
 ------------
 
+Matplotlib will automatically install dependencies when you install with
+`pip`, so this section is mostly for your reference.
+
 Matplotlib requires the following dependencies:
 
 * `Python <https://www.python.org/downloads/>`_ (>= 3.6)
@@ -240,6 +266,11 @@ and on Windows:
   - ``Agg``: the Anti-Grain Geometry C++ rendering engine;
   - ``ttconv``: a TrueType font utility.
 
+If you go this route but need to reset and rebuild to change your settings,
+remember to clear your artifacts before re-building: ::
+
+  git clean -xfd
+
 Building on Windows
 -------------------
 
diff --git a/requirements/dev/dev.txt b/requirements/dev/dev.txt
@@ -0,0 +1,19 @@
+coverage
+cycler
+flake8>=3.7
+flake8-docstrings
+ipykernel
+nbconvert[execute]
+numpy
+pillow
+pydocstyle<4.0
+pyparsing
+pytest!=4.6.0
+pytest-cov
+pytest-rerunfailures
+pytest-timeout
+pytest-xdist
+python-dateutil
+pytz
+tornado
+tox
