From e4339233802bfc3d175a754ec933691913acec20 Mon Sep 17 00:00:00 2001
From: alimcmaster1 <alimcmaster1@gmail.com>
Date: Fri, 26 Oct 2018 17:51:07 +0100
Subject: [PATCH 1/4] Isort contributing guide

---
 doc/source/contributing.rst | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
index 66d545a0de6e9..dab189bd72e2f 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/contributing.rst
@@ -612,6 +612,30 @@ Alternatively, you can install the ``grep`` and ``xargs`` commands via the
 `MinGW <http://www.mingw.org/>`__ toolchain, and it will allow you to run the
 commands above.
 
+Import Formatting
+~~~~~~~~~~~~~~~~~
+*pandas* uses `isort <https://pypi.org/project/isort/>`__ to standardise import
+formatting across the codebase. As part of :ref:`Continuous Integration <contributing.ci>` checks we run::
+
+    isort --recursive --check-only pandas
+
+to check that imports are correctly formatted as per the `setup.cfg`.
+
+If you see output like the below in :ref:`Continuous Integration <contributing.ci>` checks:
+
+.. code-block:: shell
+
+   Check import format using isort
+   ERROR: /home/travis/build/pandas-dev/pandas/pandas/io/pytables.py Imports are incorrectly sorted
+   Check import format using isort DONE
+   The command "ci/code_checks.sh" exited with 1
+
+You should run::
+
+    isort pandas/io/pytables.py
+
+to automatically format imports correctly. (Note pass the `--recursive` flag to sort all files in a directory)
+
 Backwards Compatibility
 ~~~~~~~~~~~~~~~~~~~~~~~
 

From 1c8f6197375d636fcc4d67151a2c616a88cc1e7d Mon Sep 17 00:00:00 2001
From: alimcmaster1 <alimcmaster1@gmail.com>
Date: Thu, 1 Nov 2018 22:28:45 +0000
Subject: [PATCH 2/4] Add further info to contributing guide

---
 doc/source/contributing.rst | 30 ++++++++++++++++++++++++++++--
 setup.cfg                   |  1 +
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
index dab189bd72e2f..b985659909c70 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/contributing.rst
@@ -615,7 +615,25 @@ commands above.
 Import Formatting
 ~~~~~~~~~~~~~~~~~
 *pandas* uses `isort <https://pypi.org/project/isort/>`__ to standardise import
-formatting across the codebase. As part of :ref:`Continuous Integration <contributing.ci>` checks we run::
+formatting across the codebase.
+
+A guide to import layout as per pep8 can be found `here <https://www.python.org/dev/peps/pep-0008/#imports/>`__.
+
+A summary of our current import sections ( in order ):
+
+* Future
+* Python Standard Library
+* Third Party
+* ``pandas._libs``, ``pandas.compat``, ``pandas.util._*``, ``pandas.errors`` (largely not dependent on ``pandas.core``)
+* ``pandas.core.dtypes`` (largely not dependent on the rest of ``pandas.core``)
+* Rest of ``pandas.core.*``
+* Non-core ``pandas.io``, ``pandas.plotting``, ``pandas.tseries``
+* Local application/library specific imports
+
+Imports are alphabetically sorted within these sections.
+
+
+As part of :ref:`Continuous Integration <contributing.ci>` checks we run::
 
     isort --recursive --check-only pandas
 
@@ -634,7 +652,11 @@ You should run::
 
     isort pandas/io/pytables.py
 
-to automatically format imports correctly. (Note pass the `--recursive` flag to sort all files in a directory)
+to automatically format imports correctly. This will modify your local copy of the files.
+
+The `--recursive` flag can be passed to sort all files in a directory.
+
+You can then verify the changes look ok then git :ref:`commit <contributing.commit-code>` and :ref:`push <contributing.push-code>`.
 
 Backwards Compatibility
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -1102,6 +1124,8 @@ or a new keyword argument (`example <https://github.com/pandas-dev/pandas/blob/v
 Contributing your changes to *pandas*
 =====================================
 
+.. _contributing.commit-code:
+
 Committing your code
 --------------------
 
@@ -1146,6 +1170,8 @@ Now you can commit your changes in your local repository::
 
     git commit -m
 
+.. _contributing.push-code:
+
 Pushing your changes
 --------------------
 
diff --git a/setup.cfg b/setup.cfg
index e0f1ea6fe3ac9..8a3cfd1551a46 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -76,6 +76,7 @@ exclude_lines =
 [coverage:html]
 directory = coverage_html_report
 
+# To be kept consistent with "Import Formatting" section in contributing.rst
 [isort]
 known_pre_core=pandas._libs,pandas.util._*,pandas.compat,pandas.errors
 known_dtypes=pandas.core.dtypes

From 9ec823996e1019809f726b3ccc8a3cdb5ca75a41 Mon Sep 17 00:00:00 2001
From: alimcmaster1 <alimcmaster1@gmail.com>
Date: Sat, 3 Nov 2018 17:35:44 +0000
Subject: [PATCH 3/4] Add ref

---
 doc/source/contributing.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
index b985659909c70..7af52df8b17ff 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/contributing.rst
@@ -612,6 +612,8 @@ Alternatively, you can install the ``grep`` and ``xargs`` commands via the
 `MinGW <http://www.mingw.org/>`__ toolchain, and it will allow you to run the
 commands above.
 
+.. _contributing.import-formatting:
+
 Import Formatting
 ~~~~~~~~~~~~~~~~~
 *pandas* uses `isort <https://pypi.org/project/isort/>`__ to standardise import

From a06ac9753d25dcf42588606eeb0c410ee4c1e45b Mon Sep 17 00:00:00 2001
From: Marc Garcia <garcia.marc@gmail.com>
Date: Sat, 3 Nov 2018 23:19:25 +0000
Subject: [PATCH 4/4] Add comma

Co-Authored-By: alimcmaster1 <alimcmaster1@gmail.com>
---
 doc/source/contributing.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
index 7af52df8b17ff..3ec505998fde0 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/contributing.rst
@@ -658,7 +658,7 @@ to automatically format imports correctly. This will modify your local copy of t
 
 The `--recursive` flag can be passed to sort all files in a directory.
 
-You can then verify the changes look ok then git :ref:`commit <contributing.commit-code>` and :ref:`push <contributing.push-code>`.
+You can then verify the changes look ok, then git :ref:`commit <contributing.commit-code>` and :ref:`push <contributing.push-code>`.
 
 Backwards Compatibility
 ~~~~~~~~~~~~~~~~~~~~~~~