From 4300976ba47ad8562985fe9a356c879f3f7b8c4d Mon Sep 17 00:00:00 2001 From: Bill Little Date: Tue, 11 Apr 2023 14:45:05 +0100 Subject: [PATCH] clarity on whatsnew entry contributors --- .../contributing_pull_request_checklist.rst | 6 ++-- .../documenting/whats_new_contributions.rst | 28 ++++++++++++------- 2 files changed, 21 insertions(+), 13 deletions(-) diff --git a/docs/src/developers_guide/contributing_pull_request_checklist.rst b/docs/src/developers_guide/contributing_pull_request_checklist.rst index 62177def6e..11d68ace46 100644 --- a/docs/src/developers_guide/contributing_pull_request_checklist.rst +++ b/docs/src/developers_guide/contributing_pull_request_checklist.rst @@ -6,12 +6,12 @@ Pull Request Checklist ====================== 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 +process of merging. It is the responsibility of the contributor submitting a pull request to do their best to deliver a pull request which meets the 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. +This check list summarises criteria which will be checked before a pull request +is merged. Before submitting a pull request please consider the following: #. **Provide a helpful description** of the Pull Request. This should include: diff --git a/docs/src/developers_guide/documenting/whats_new_contributions.rst b/docs/src/developers_guide/documenting/whats_new_contributions.rst index aa19722a69..82569e57a0 100644 --- a/docs/src/developers_guide/documenting/whats_new_contributions.rst +++ b/docs/src/developers_guide/documenting/whats_new_contributions.rst @@ -53,8 +53,8 @@ merge from trunk. Writing a Contribution ====================== -As introduced above, a contribution is the description of a change to Iris -which improved Iris in some way. As such, a single Iris Pull Request may +A contribution is the short description of a change introduced to Iris +which improved it 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. @@ -67,23 +67,31 @@ exceed **column 80** and ensure that any subsequent lines of the same entry 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 - user name. Link the name to their GitHub profile. E.g. - ```@tkknight `_ changed...`` +* Use your discretion to decide on the names of all those that you want to + acknowledge as part of your contribution. Also consider the efforts of the + reviewer. Please use GitHub user names that link to their GitHub profile + e.g., - * Bigger changes take a lot of effort to review, too! Make sure you credit - the reviewer(s) where appropriate. + ```@tkknight`_ Lorem ipsum dolor sit amet ...`` -* The new/changed behaviour + Also add a full reference in the following section at the end of the ``latest.rst``:: + + .. comment + Whatsnew author names (@github name) in alphabetical order. Note that, + core dev names are automatically included by the common_links.inc: + + .. _@tkknight: https://github.com/tkknight + +* A succinct summary of 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. -* Pull request references, bracketed, following the final period. E.g. +* Pull request references, bracketed, following the final period e.g., ``(:pull:`1111`, :pull:`9999`)`` -* A trailing blank line (standard reStructuredText list format) +* A trailing blank line (standard reStructuredText list format). For example::