broke release info out into seperate section, tweaked some other wording

story645 · timhoffm · melissawm · story645 · commit 7e79c01d3e6e · 2022-10-15T21:30:33.000-04:00
documented directive policy

Co-authored-by: Tim Hoffmann &lt;2836374+timhoffm@users.noreply.github.com&gt;
Co-authored-by: melissawm &lt;melissawm@gmail.com&gt;
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -8,10 +8,13 @@
 - [ ] Is [Flake 8](https://flake8.pycqa.org/en/latest/) compliant (install `flake8-docstrings` and run `flake8 --docstring-convention=all`).
 
 **Documentation**
-- [ ] New features are documented, with examples if plot related.
-- [ ] New features have an entry in `doc/users/next_whats_new/` (follow instructions in README.rst there).
-- [ ] API changes documented in `doc/api/next_api_changes/` (follow instructions in README.rst there).
 - [ ] Documentation is sphinx and numpydoc compliant (the docs should [build](https://matplotlib.org/devel/documenting_mpl.html#building-the-docs) without error).
+- [ ] New plotting related features are documented with examples.
+
+**Release Notes**
+- [ ] New features are marked with a `.. versionadded::` directive in the docstring and documented in `doc/users/next_whats_new/`
+- [ ] API changes are marked with a `.. versionchanged::` directive in the docstring and documented in `doc/api/next_api_changes/`
+- [ ] Release notes conform with instructions in  `next_whats_new/README.rst` or `next_api_changes/README.rst`
 
 <!--
 Thank you so much for your PR!  To help us review your contribution, please
@@ -22,7 +25,7 @@ consider the following points:
 - Help with git and github is available at
   https://matplotlib.org/devel/gitwash/development_workflow.html.
 
-- Do not create the PR out of main, but out of a separate branch.
+- Create a separate branch for your changes and open the PR from this branch. Please avoid working on `main`.
 
 - The PR title should summarize the changes, for example "Raise ValueError on
   non-numeric input to set_xlim".  Avoid non-descriptive titles such as
diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst
@@ -108,13 +108,60 @@ Documentation
 
 * See :ref:`documenting-matplotlib` for our documentation style guide.
 
-* If your change is a major new feature, add an entry to
-  :file:`doc/users/whats_new.rst`.
+.. _release_notes:
 
-* If you change the API in a backward-incompatible way, please
-  document it by adding a file in the relevant subdirectory of
-  :file:`doc/api/next_api_changes/`, probably in the ``behavior/``
-  subdirectory.
+New features and API changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When adding a major new feature or changing the API in a backward incompatible
+way, please document it by including a versioning directive in the docstring
+and adding an entry to the folder for either the what's new or API change notes.
+
++-------------------+-----------------------------+----------------------------------+
+| for this addition | include this directive      | create entry in this folder      |
++===================+=============================+==================================+
+| new feature       | ``.. versionadded:: v3.N``  | :file:`doc/users/next_whats_new/` |
++-------------------+-----------------------------+----------------------------------+
+| API change        | ``.. versionchanged:: v3.N``| :file:`doc/api/next_api_changes/`|
+|                   |                             |                                  |
+|                   |                             | probably in ``behavior/``        |
++-------------------+-----------------------------+----------------------------------+
+
+The directives should be placed at the end of a description block. For example::
+
+  class Foo:
+      """
+      This is the summary.
+
+      Followed by a longer description block.
+
+      Consisting of multiple lines and paragraphs.
+
+      .. versionadded:: 3.5
+
+      Parameters
+      ----------
+      a : int
+          The first parameter.
+      b: bool, default: False
+          This was added later.
+
+          .. versionadded:: 3.6
+      """
+
+      def set_b(b):
+          """
+          Set b.
+
+          .. versionadded:: 3.6
+
+          Parameters
+          ----------
+          b: bool
+
+For classes and functions, the directive should be placed before the
+*Parameters* section. For parameters, the directive should be placed at the
+end of the parameter description. The patch release version is omitted and
+the directive should not be added to entire modules.
 
 .. _pr-labels:
 
