Internal "What's New" entries and other WN improvements

.github/pull_request_template.md

@@ -0,0 +1,5 @@
+**Authors and Reviewers:** please make sure this pull request complies as much
+as possible with the
+[Iris pull request check list]( https://scitools-iris.readthedocs.io/en/latest/developers_guide/pulls.html#the-iris-check-list).
+
+---

docs/iris/src/developers_guide/documenting/docstrings.rst

@@ -1,3 +1,5 @@
+.. _docstrings:
+
 ==========
 Docstrings
 ==========
@@ -7,7 +9,7 @@ appropriate docstring.
 
 This document has been influenced by the following PEP's,
 
-   * Attribute Docstrings `PEP-224 <http://www.python.org/dev/peps/pep-0224/>`_ 
+   * Attribute Docstrings `PEP-224 <http://www.python.org/dev/peps/pep-0224/>`_
    * Docstring Conventions `PEP-257 <http://www.python.org/dev/peps/pep-0257/>`_
 
 
@@ -42,7 +44,7 @@ Here is a simple example of a standard docstring:
 This would be rendered as:
 
    .. currentmodule:: documenting.docstrings_sample_routine
-   
+
    .. automodule:: documenting.docstrings_sample_routine
       :members:
       :undoc-members:

docs/iris/src/developers_guide/documenting/whats_new_contributions.rst

@@ -10,8 +10,34 @@ document are written by the developer most familiar with the change made.
 The contribution should be included as part of the Iris Pull Request that
 introduces the change.
 
-The ``latest.rst`` and the past release notes are kept in 
-``docs/iris/src/whatsnew/``.
+The ``latest.rst`` and the past release notes are kept in
+``docs/iris/src/whatsnew/``. If you are writing the first contribution after
+an Iris release: **create the new** ``latest.rst`` by copying the content from
+``latest.rst.template`` in the same directory.
+
+Since the `Contribution categories`_ include Internal changes, **all** Iris
+Pull Requests should be accompanied by a "What's New" contribution.
+
+
+Git Conflicts
+=============
+
+If changes to ``latest.rst`` are being suggested in several simultaneous
+Iris Pull Requests, Git will likely encounter merge conflicts. In you think
+this situation is likely (large PR, high repo activity etc.): wait until your
+code is ready for review, then create a **new pull request** specifically for
+the "What's New" entry, referencing the main pull request and titled
+(e.g. for PR#9999):
+
+  What's New for #9999
+
+If the entry references something new introduced by the main pull request then
+such links will not be valid yet. The reviewer should **merge the main pull
+request first**, followed by the "What's New" pull request.
+
+These measures should mean the suggested ``latest.rst`` changes are outstanding
+for the minimum time, minimising conflicts and minimising the need to rebase or
+merge from trunk.
 
 
 Writing a contribution
@@ -22,28 +48,49 @@ which improved Iris in some way. As such, a single Iris Pull Request may
 contain multiple changes that are worth highlighting as contributions to the
 what's new document.
 
+The appropriate contribution for a pull request might in fact be an addition or
+change to an existing "What's New" entry.
+
 Each contribution will ideally be written as a single concise bullet point
-in a reStructuredText format with a trailing blank line.  For example::
+in a reStructuredText format. Where possible do not exceed **column 80** and
+ensure that any subsequent lines of the same bullet point are aligned with the
+first. The content should target an Iris user as the audience. The required
+content, in order, is as follows:
+
+* Names of those who contributed the change. These should be their GitHub
+  display name, or if that is not available use their GitHub user name. Link
+  the name to their GitHub profile. E.g.
+  ```Bill Little <https://github.com/bjlittle>`_ and
+  `tkknight <https://github.com/tkknight>`_ changed...``
+
+* The new/changed behaviour
+
+* Context to the change. Possible examples include: what this fixes, why
+  something was added, issue references (e.g. ``:issue:`9999```), more specific
+  detail on the change itself.
 
-  * Fixed :issue:`9999`.  Lorem ipsum dolor sit amet, consectetur adipiscing 
-    elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
-    <blank line>
+* Pull request references, bracketed, following the final period. E.g.
+  ``(:pull:`1111`, :pull:`9999`)``
 
-Note that this example also cites the related issue, optionally you may also
-include the pull request using the notation ``:pull:`9999```.  Where possible
-do not exceed **column 80** and ensure that any subsequent lines
-of the same bullet point is aligned with the first.  
+* A trailing blank line (standard reStructuredText bullet format)
 
-The content of the bullet point should highlight the change that has been made
-to Iris, targeting an Iris user as the audience.
+For example::
 
-For inspiration that may include adding links to code please examine past
-what's :ref:`iris_whatsnew` entries.  
+  * `Bill Little <https://github.com/bjlittle>`_ and
+    `tkknight <https://github.com/tkknight>`_ changed changed argument ``x``
+    to be optional in :class:`~iris.module.class` and
+    :meth:`iris.module.method`. This allows greater flexibility as requested in
+    :issue:`9999`. (:pull:`1111`, :pull:`9999`)
+
+
+The above example also demonstrates some of the possible syntax for including
+links to code. For more inspiration on possible content and references please
+examine past what's :ref:`iris_whatsnew` entries.
 
 .. note:: The reStructuredText syntax will be checked as part of building
-          the documentation.  Any warnings should be corrected.  
+          the documentation.  Any warnings should be corrected.
           `travis-ci`_ will automatically build the documentation when
-          creating a pull request, however you can also manually 
+          creating a pull request, however you can also manually
           :ref:`build <contributing.documentation.building>` the documentation.
 
 .. _travis-ci: https://travis-ci.org/github/SciTools/iris
@@ -64,12 +111,15 @@ users.  To achieve this several categories may be used.
 *Incompatible Changes*
   A change that causes an incompatibility with prior versions of Iris.
 
-*Internal*
-  Changes to any internal or development related topics, such as testing,
-  environment dependencies etc
-
 *Deprecations*
   Deprecations of functionality.
 
+*Dependencies*
+  Additions, removals and version changes in Iris' package dependencies.
+
 *Documentation*
   Changes to documentation.
+
+*Internal*
+  Changes to any internal or development related topics, such as testing,
+  environment dependencies etc

docs/iris/src/developers_guide/pulls.rst

@@ -1,7 +1,7 @@
 .. _pr_check:
 
 
-Pull request check List
+Pull request check list
 ***********************
 
 A pull request to a SciTools project master should be ready to merge into the
@@ -10,7 +10,7 @@ master branch.
 All pull request will be reviewed by a core developer who will manage the
 process of merging. It is the responsibility of a developer submitting a
 pull request to do their best to deliver a pull request which meets the
-requirements of the project it is submitted to. 
+requirements of the project it is submitted to.
 
 The check list summarises criteria which will be checked before a pull request
 is merged.  Before submitting a pull request please consider this list.
@@ -24,33 +24,26 @@ The Iris check list
 
  * the aim of the change ; the problem addressed ; a link to the issue.
  * how the change has been delivered.
- * a "What's New" entry, submitted as a new file added in the pull request.
-   See `Contributing a "What's New" entry`_.
+ * a "What's New" entry - see :ref:`whats_new_contributions`.
 
 * Do all the tests pass locally?
 
- * The Iris tests may be run with ``python setup.py test`` which has a command 
+ * The Iris tests may be run with ``python setup.py test`` which has a command
    line utility included.
 
 * Have new tests been provided for all additional functionality?
 
-* Do all modified and new source files pass PEP8?
+* Do all modified and new source files conform to the required
+  :ref:`iris_code_format`?
 
- * PEP8_ is the Python source code style guide.
- * There is a python module for checking pep8 compliance: python-pep8_
- * a standard Iris test checks that all source files meet PEP8 compliance
-   (see "iris.tests.test_coding_standards.TestCodeFormat").
-
-* Do all modified and new source files have a correct, up-to-date copyright
-  header?
+* Do all modified and new source files have a correct copyright header?
 
  * a standard Iris test checks that all source files include a copyright
-   message, including the correct year of the latest change
-   (see "iris.tests.test_coding_standards.TestLicenseHeaders").
+   message (see "iris.tests.test_coding_standards.TestLicenseHeaders").
 
 * Has the documentation been updated to explain all new or changed features?
 
- * refer to the developer guide on docstrings_
+ * refer to the developer guide on :ref:`docstrings`
 
 * Have code examples been provided inside docstrings, where relevant?
 
@@ -67,8 +60,7 @@ The Iris check list
 
 * Have you provided a "what's new" contribution?
 
- * this should be done for all changes that affect API or behaviour.
-   See :ref:`whats_new_contributions`
+ * this should be done for **all** changes - see :ref:`whats_new_contributions`
 
 * Does the documentation build without errors?
 
@@ -98,7 +90,7 @@ The Iris check list
     tests.
   * iris-sample-data_ is a github project containing all the data to support
     the gallery and examples.
-  * test-images-scitools_ is a github project containing reference plot images
+  * test-iris-imagehash_ is a github project containing reference plot images
     to support iris graphics tests : see :ref:`developer_graphics_tests`.
 
  * If new files are required by tests or code examples, they must be added to
@@ -112,6 +104,4 @@ The Iris check list
 .. _conda: https://docs.conda.io/en/latest/
 .. _iris-test-data: https://github.com/SciTools/iris-test-data
 .. _iris-sample-data: https://github.com/SciTools/iris-sample-data
-.. _test-images-scitools: https://github.com/SciTools/test-images-scitools
-.. _docstrings: http://scitools.org.uk/iris/docs/latest/developers_guide/documenting/docstrings.html
-.. _Contributing a "What's New" entry: http://scitools.org.uk/iris/docs/latest/developers_guide/documenting/whats_new_contributions.html
+.. _test-iris-imagehash: https://github.com/SciTools/test-iris-imagehash