Skip to content

Versioning directives policy #24161

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 26, 2022
Merged

Versioning directives policy #24161

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions .github/PULL_REQUEST_TEMPLATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
59 changes: 53 additions & 6 deletions doc/devel/coding_guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:: 3.N`` | :file:`doc/users/next_whats_new/`|
+-------------------+-----------------------------+----------------------------------+
| API change | ``.. versionchanged:: 3.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:

Expand Down