Developer guide overhaul (#3852)

* developer guide overhaul baseline

* added todo

* added todos

* Addressed all todos.

* Updated PR template

* Corrected spelling

* Used ref intead of a relative url.

* Added a ref for the developers guide

* Minor updates to address reviewer comments

* review action: fix generated dir reference

* review actions

Co-authored-by: Bill Little <[email protected]>

.github/CONTRIBUTING.md

@@ -1,36 +1 @@
-How to contribute
-=================
-
-We want Iris to be driven by the community - your contributions are
-invaluable to us! This page lists the guidelines for contributors which
-will help ease the process of getting your hard work accepted into Iris,
-and shared back to the world.
-
-Getting started
----------------
-
-1. If you've not already got one, sign up for a
-   [GitHub account](https://github.com/signup/free).
-1. Fork the Iris repository, create your new fix/feature branch, and
-   start commiting code.
- - Our
-   [development guide](https://scitools.org.uk/iris/docs/latest/developers_guide/index.html)
-   has more detail.
-1. Make sure you've added appropriate tests, and that *all* the tests
-   pass.
-
-
-Submitting changes
-------------------
-
-1. Read and sign the Contributor Licence Agreement (CLA).
- - See our [governance page](http://scitools.org.uk/governance.html)
-   for the CLA and what to do with it.
-1. Push your branch to your fork of Iris.
-1. Submit your pull request.
-1. Chillax.
-
-
-If in doubt, please
-[contact us](https://groups.google.com/forum/?fromgroups=#!forum/scitools-iris)
-on our Google Group, and we'll be happy to help you.
+See the [Developers Guide](https://scitools-iris.readthedocs.io/en/latest/index.html#development-index)

.github/pull_request_template.md

@@ -6,4 +6,4 @@
 
 
 ---
-[Consult Iris pull request check list]( https://scitools-iris.readthedocs.io/en/latest/developers_guide/pulls.html#the-iris-check-list)
+[Consult Iris pull request check list]( https://scitools-iris.readthedocs.io/en/latest/developers_guide/contributing_pull_request_checklist.html)

docs/iris/src/common_links.inc

@@ -0,0 +1,24 @@
+.. _SciTools: https://github.com/SciTools
+.. _Iris: https://github.com/SciTools/iris
+.. _Iris GitHub: https://github.com/SciTools/iris
+.. _iris mailing list: https://groups.google.com/forum/#!forum/scitools-iris
+.. _issue: https://github.com/SciTools/iris/issues
+.. _issues: https://github.com/SciTools/iris/issues
+.. _pull request: https://github.com/SciTools/iris/pulls
+.. _pull requests: https://github.com/SciTools/iris/pulls
+.. _contributor: https://github.com/SciTools/scitools.org.uk/blob/master/contributors.json
+.. _core developers: https://github.com/SciTools/scitools.org.uk/blob/master/contributors.json
+.. _iris-test-data: https://github.com/SciTools/iris-test-data
+.. _iris-sample-data: https://github.com/SciTools/iris-sample-data
+.. _test-iris-imagehash: https://github.com/SciTools/test-iris-imagehash
+.. _readthedocs.yml: https://github.com/SciTools/iris/blob/master/requirements/ci/readthedocs.yml
+.. _travis-ci: https://travis-ci.org/github/SciTools/iris
+.. _.travis.yml: https://github.com/SciTools/iris/blob/master/.travis.yml
+.. _.stickler.yml: https://github.com/SciTools/iris/blob/master/.stickler.yml
+.. _.flake8.yml: https://github.com/SciTools/iris/blob/master/.flake8
+.. _GitHub Help Documentation: https://docs.github.com/en/github
+.. _using git: https://docs.github.com/en/github/using-git
+.. _generating sss keys for GitHub: https://docs.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account
+.. _New Issue: https://github.com/scitools/iris/issues/new/choose
+.. _matplotlib: https://matplotlib.org/
+.. _conda: https://docs.conda.io/en/latest/

docs/iris/src/conf.py

@@ -243,6 +243,7 @@ def autolog(message):
     "https://github.com/SciTools/iris/commit/69597eb3d8501ff16ee3d56aef1f7b8f1c2bb316#diff-1680206bdc5cfaa83e14428f5ba0f848",
     "http://www.wmo.int/pages/prog/www/DPFS/documents/485_Vol_I_en_colour.pdf",
     "http://code.google.com/p/msysgit/downloads/list",
+    "http://schacon.github.com/git",
 ]
 
 # list of sources to exclude from the build.

docs/iris/src/developers_guide/contributing_changes.rst

@@ -0,0 +1,11 @@
+
+.. _contributing.changes:
+
+Contributing your changes
+=========================
+
+.. toctree::
+   :maxdepth: 3
+
+   documenting/whats_new_contributions
+   contributing_pull_request_checklist

docs/iris/src/developers_guide/contributing_ci_tests.rst

@@ -0,0 +1,65 @@
+.. _developer_testing_ci:
+
+.. include:: ../common_links.inc
+
+Continuous Integration (CI) Testing
+===================================
+
+The `Iris`_ GitHub repository is configured to run checks on the code
+automatically when a pull request is created, updated or merged against
+Iris **master**.  The checks performed are:
+
+* :ref:`testing_cla`
+* :ref:`testing_travis`
+* :ref:`testing_stickler`
+
+
+.. _testing_cla:
+
+SciTools CLA Checker
+********************
+
+A bot that checks the user who created the pull request has signed the
+**Contributor's License Agreement (CLA)**.  For more information on this this
+please see https://scitools.org.uk/organisation.html#governance
+
+
+.. _testing_stickler:
+
+Stickler CI
+***********
+
+Automatically enforces coding standards.  The configuration file named
+`.stickler.yml`_ is in the Iris_ root directory.  For more information see
+https://stickler-ci.com/.
+
+
+.. _testing_travis:
+
+Travis-CI
+*********
+
+The unit and integration tests in Iris are an essential mechanism to ensure
+that the Iris code base is working as expected.  :ref:`developer_running_tests`
+may be run manually but to ensure the checks are performed a
+continuous integration testing tool named `travis-ci`_ is used.
+
+A `travis-ci`_ configuration file named `.travis.yml`_
+is in the Iris repository which tells travis-ci what commands to run.  The
+commands include retrieving the Iris code base and associated test files using
+conda and then running the tests.  `travis-ci`_ allows for a matrix of tests to
+be performed to ensure that all expected variations test successfully.
+
+The `travis-ci`_ tests are run automatically against the `Iris`_ master
+repository when a pull request is submitted, updated or merged.
+
+GitHub Checklist
+****************
+
+An example snapshot from a successful GitHub pull request shows all test passing.
+
+.. image:: ci_checks.png
+
+If any CI checks fail, then the pull request is unlikely to be merged to the Iris
+target branch by a core developer.
+

docs/iris/src/developers_guide/contributing_code_formatting.rst

@@ -0,0 +1,63 @@
+.. include:: ../common_links.inc
+
+.. _code_formatting:
+
+Code formatting
+===============
+
+To ensure a consistent code format throughout Iris, we recommend using
+tools to check the source directly.
+
+* `black`_ for an opinionated coding auto-formatter
+* `flake8`_ linting checks
+
+The preferred way to run these tools automatically is to setup and configure
+`pre-commit`_.
+
+You can install ``pre-commit`` in your development environment using ``pip``::
+
+    $ pip install pre-commit
+
+or alternatively using ``conda``::
+
+    $ conda install -c conda-forge pre-commit
+
+.. note:: If you have setup your Python environment using the guide
+         :ref:`installing_from_source` then ``pre-commit`` should already
+         be present.
+
+In order to install the ``pre-commit`` git hooks defined in our
+``.pre-commit-config.yaml`` file, you must now run the following command from
+the root directory of Iris::
+
+    $ pre-commit install
+
+Upon performing a ``git commit``, your code will now be automatically formatted
+to the ``black`` configuration defined in our ``pyproject.toml`` file, and
+linted according to our ``.flake8`` configuration file. Note that,
+``pre-commit`` will automatically download and install the necessary packages
+for each ``.pre-commit-config.yaml`` git hook.
+
+Additionally, you may wish to enable ``black`` for your preferred
+`editor/IDE <https://black.readthedocs.io/en/stable/editor_integration.html#editor-integration>`_.
+
+With the ``pre-commit`` configured, the output of performing a ``git commit``
+will look similar to::
+
+    Check for added large files..............................................Passed
+    Check for merge conflicts................................................Passed
+    Debug Statements (Python)............................(no files to check)Skipped
+    Don't commit to branch...................................................Passed
+    black................................................(no files to check)Skipped
+    flake8...............................................(no files to check)Skipped
+    [contribution_overhaul c8513187] this is my commit message
+    2 files changed, 10 insertions(+), 9 deletions(-)
+
+
+.. note:: You can also run `black`_ and `flake8`_ manually.  Please see the
+          their officially documentation for more information.
+
+
+.. _black: https://black.readthedocs.io/en/stable/
+.. _flake8: https://flake8.pycqa.org/en/stable/
+.. _pre-commit: https://pre-commit.com/

docs/iris/src/developers_guide/contributing_codebase_index.rst

@@ -0,0 +1,13 @@
+.. _contributing.documentation.codebase:
+
+Contributing to the code base
+=============================
+
+.. toctree::
+   :maxdepth: 3
+
+   contributing_code_formatting
+   documenting/docstrings
+   documenting/rest_guide
+   contributing_deprecations
+   contributing_testing_index