From 634dbd326f33c9feb957fe545efebd691741841d Mon Sep 17 00:00:00 2001 From: Richard Shadrach Date: Wed, 7 Jul 2021 11:05:02 -0400 Subject: [PATCH 1/2] DOC: Add more instructions for updating the whatsnew --- doc/source/development/contributing_codebase.rst | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/doc/source/development/contributing_codebase.rst b/doc/source/development/contributing_codebase.rst index e812aaa760a8f..12e6b43aac296 100644 --- a/doc/source/development/contributing_codebase.rst +++ b/doc/source/development/contributing_codebase.rst @@ -812,7 +812,14 @@ Changes should be reflected in the release notes located in ``doc/source/whatsne This file contains an ongoing change log for each release. Add an entry to this file to document your fix, enhancement or (unavoidable) breaking change. Make sure to include the GitHub issue number when adding your entry (using ``:issue:`1234``` where ``1234`` is the -issue/pull request number). +issue/pull request number). Your entry should be written using full sentences and proper +grammar. + +When mentioning parts of the API, use a Sphinx ``:func:``, ``:meth:``, or ``:class:`` +directive as appropriate. Not all public API functions and methods have a +documentation page; ideally links would only be added if they resolve. You can +usually find similar examples by checking the release notes for one of the previous +versions. If your code is an enhancement, it is most likely necessary to add usage examples to the existing documentation. This can be done following the section @@ -828,3 +835,10 @@ This will put the text *New in version 1.1.0* wherever you put the sphinx directive. This should also be put in the docstring when adding a new function or method (`example `__) or a new keyword argument (`example `__). + +If your code is a bugfix, add your entry to the relevant bugfix section. Avoid +adding to the ``Other`` section; only in rare cases should entries go here. +Being as concise as possible, the description of the bug should include how the +user may encounter it and an indication of the bug itself, e.g. +"produces incorrect results" or "incorrectly raises". It may be necessary to also +indicate the new behavior. From 1dad8029970729d11de5eb23fa142ecb9f088ae6 Mon Sep 17 00:00:00 2001 From: Richard Shadrach Date: Wed, 7 Jul 2021 14:06:01 -0400 Subject: [PATCH 2/2] Improvements --- doc/source/development/contributing_codebase.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/source/development/contributing_codebase.rst b/doc/source/development/contributing_codebase.rst index 12e6b43aac296..721b1af126709 100644 --- a/doc/source/development/contributing_codebase.rst +++ b/doc/source/development/contributing_codebase.rst @@ -821,6 +821,13 @@ documentation page; ideally links would only be added if they resolve. You can usually find similar examples by checking the release notes for one of the previous versions. +If your code is a bugfix, add your entry to the relevant bugfix section. Avoid +adding to the ``Other`` section; only in rare cases should entries go there. +Being as concise as possible, the description of the bug should include how the +user may encounter it and an indication of the bug itself, e.g. +"produces incorrect results" or "incorrectly raises". It may be necessary to also +indicate the new behavior. + If your code is an enhancement, it is most likely necessary to add usage examples to the existing documentation. This can be done following the section regarding :ref:`documentation `. @@ -835,10 +842,3 @@ This will put the text *New in version 1.1.0* wherever you put the sphinx directive. This should also be put in the docstring when adding a new function or method (`example `__) or a new keyword argument (`example `__). - -If your code is a bugfix, add your entry to the relevant bugfix section. Avoid -adding to the ``Other`` section; only in rare cases should entries go here. -Being as concise as possible, the description of the bug should include how the -user may encounter it and an indication of the bug itself, e.g. -"produces incorrect results" or "incorrectly raises". It may be necessary to also -indicate the new behavior.