Skip to content

Commit 8454605

Browse files
story645timhoffmmelissawmQuLogic
committed
PR template: broke release info out into seperate section and tweaked some other wording
Coding guide: documented directive policy Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Co-authored-by: melissawm <melissawm@gmail.com> Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>
1 parent 5fe74c2 commit 8454605

File tree

2 files changed

+60
-10
lines changed

2 files changed

+60
-10
lines changed

‎.github/PULL_REQUEST_TEMPLATE.md

+7-4
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,13 @@
88
- [ ] Is [Flake 8](https://flake8.pycqa.org/en/latest/) compliant (install `flake8-docstrings` and run `flake8 --docstring-convention=all`).
99

1010
**Documentation**
11-
- [ ] New features are documented, with examples if plot related.
12-
- [ ] New features have an entry in `doc/users/next_whats_new/` (follow instructions in README.rst there).
13-
- [ ] API changes documented in `doc/api/next_api_changes/` (follow instructions in README.rst there).
1411
- [ ] Documentation is sphinx and numpydoc compliant (the docs should [build](https://matplotlib.org/devel/documenting_mpl.html#building-the-docs) without error).
12+
- [ ] New plotting related features are documented with examples.
13+
14+
**Release Notes**
15+
- [ ] New features are marked with a `.. versionadded::` directive in the docstring and documented in `doc/users/next_whats_new/`
16+
- [ ] API changes are marked with a `.. versionchanged::` directive in the docstring and documented in `doc/api/next_api_changes/`
17+
- [ ] Release notes conform with instructions in `next_whats_new/README.rst` or `next_api_changes/README.rst`
1518

1619
<!--
1720
Thank you so much for your PR! To help us review your contribution, please
@@ -22,7 +25,7 @@ consider the following points:
2225
- Help with git and github is available at
2326
https://matplotlib.org/devel/gitwash/development_workflow.html.
2427
25-
- Do not create the PR out of main, but out of a separate branch.
28+
- Create a separate branch for your changes and open the PR from this branch. Please avoid working on `main`.
2629
2730
- The PR title should summarize the changes, for example "Raise ValueError on
2831
non-numeric input to set_xlim". Avoid non-descriptive titles such as

‎doc/devel/coding_guide.rst

+53-6
Original file line numberDiff line numberDiff line change
@@ -108,13 +108,60 @@ Documentation
108108

109109
* See :ref:`documenting-matplotlib` for our documentation style guide.
110110

111-
* If your change is a major new feature, add an entry to
112-
:file:`doc/users/whats_new.rst`.
111+
.. _release_notes:
113112

114-
* If you change the API in a backward-incompatible way, please
115-
document it by adding a file in the relevant subdirectory of
116-
:file:`doc/api/next_api_changes/`, probably in the ``behavior/``
117-
subdirectory.
113+
New features and API changes
114+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
115+
When adding a major new feature or changing the API in a backward incompatible
116+
way, please document it by including a versioning directive in the docstring
117+
and adding an entry to the folder for either the what's new or API change notes.
118+
119+
+-------------------+-----------------------------+----------------------------------+
120+
| for this addition | include this directive | create entry in this folder |
121+
+===================+=============================+==================================+
122+
| new feature | ``.. versionadded:: 3.N`` | :file:`doc/users/next_whats_new/`|
123+
+-------------------+-----------------------------+----------------------------------+
124+
| API change | ``.. versionchanged:: 3.N`` | :file:`doc/api/next_api_changes/`|
125+
| | | |
126+
| | | probably in ``behavior/`` |
127+
+-------------------+-----------------------------+----------------------------------+
128+
129+
The directives should be placed at the end of a description block. For example::
130+
131+
class Foo:
132+
"""
133+
This is the summary.
134+
135+
Followed by a longer description block.
136+
137+
Consisting of multiple lines and paragraphs.
138+
139+
.. versionadded:: 3.5
140+
141+
Parameters
142+
----------
143+
a : int
144+
The first parameter.
145+
b: bool, default: False
146+
This was added later.
147+
148+
.. versionadded:: 3.6
149+
"""
150+
151+
def set_b(b):
152+
"""
153+
Set b.
154+
155+
.. versionadded:: 3.6
156+
157+
Parameters
158+
----------
159+
b: bool
160+
161+
For classes and functions, the directive should be placed before the
162+
*Parameters* section. For parameters, the directive should be placed at the
163+
end of the parameter description. The patch release version is omitted and
164+
the directive should not be added to entire modules.
118165

119166
.. _pr-labels:
120167

0 commit comments

Comments
 (0)