Please avoid using references in section titles, as it causes links to be

confusing in the table of contents. Instead, ensure that a reference is

included in the descriptive text. A typical entry could look like this::

It is recommended to check that your contribution complies with the following

rules before submitting a pull request:

* If your pull request addresses an issue, please use the title to describe the

issue (e.g. "Add ability to plot timedeltas") and mention the issue number

in the pull request description to ensure that a link is created to the

original issue (e.g. "Closes #8869" or "Fixes #8869"). This will ensure the

original issue mentioned is automatically closed when your PR is merged. See

`the GitHub documentation

<https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue>`__

for more details.

* Formatting should follow the recommendations of PEP8_, as enforced by

flake8_. Matplotlib modifies PEP8 to extend the maximum line length to 88

characters. You can check flake8 compliance from the command line with ::

or your editor may provide integration with it. Note that Matplotlib

intentionally does not use the black_ auto-formatter (1__), in particular due

to its inability to understand the semantics of mathematical expressions

(2__, 3__).

.. _PEP8: https://www.python.org/dev/peps/pep-0008/

.. _flake8: https://flake8.pycqa.org/

.. _black: https://black.readthedocs.io/

.. __: https://github.com/matplotlib/matplotlib/issues/18796

.. __: https://github.com/psf/black/issues/148

.. __: https://github.com/psf/black/issues/1984

* All public methods should have informative docstrings with sample usage when

appropriate. Use the :ref:`docstring standards <writing-docstrings>`.

* For high-level plotting functions, consider adding a simple example either in

the ``Example`` section of the docstring or the

:ref:`examples gallery <gallery>`.

* Changes (both new features and bugfixes) should have good test coverage. See

:ref:`testing` for more details.

* Import the following modules using the standard scipy conventions::

* If your change is a major new feature, add an entry to the ``What's new``

section by adding a new file in ``doc/users/next_whats_new`` (see

:file:`doc/users/next_whats_new/README.rst` for more information).

* If you change the API in a backward-incompatible way, please document it in

:file:`doc/api/next_api_changes/behavior`, by adding a new file with the

naming convention ``99999-ABC.rst`` where the pull request number is followed

by the contributor's initials. (see :file:`doc/api/api_changes.rst` for more

information)

* If you add new public API or change public API, update or add the

corresponding type hints. Most often this is found in the corresponding

``.pyi`` file for the ``.py`` file which was edited. Changes in ``pyplot.py``

are type hinted inline.

* See below for additional points about :ref:`keyword-argument-processing`, if

applicable for your pull request.

The current state of the Matplotlib code base is not compliant with all

of these guidelines, but we expect that enforcing these constraints on all

new contributions will move the overall code base quality in the right

direction.

.. seealso::

* :ref:`coding_guidelines`

* :ref:`testing`

* :ref:`documenting-matplotlib`

Summary for pull request authors

.. note::

* We value contributions from people with all levels of experience. In

particular if this is your first PR not everything has to be perfect.

We'll guide you through the PR process.

* Nevertheless, please try to follow the guidelines below as well as you can to

help make the PR process quick and smooth.

* Be patient with reviewers. We try our best to respond quickly, but we

have limited bandwidth. If there is no feedback within a couple of days,

please ping us by posting a comment to your PR.

* :ref:`Target the main branch <pr-branch-selection>`.

* Adhere to the :ref:`coding_guidelines`.

* Update the :ref:`documentation <pr-documentation>` if necessary.

* Aim at making the PR as "ready-to-go" as you can. This helps to speed up

the review process.

* It is ok to open incomplete or work-in-progress PRs if you need help or

feedback from the developers. You may mark these as

`draft pull requests <https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests>`_

on GitHub.

* When updating your PR, instead of adding new commits to fix something, please

consider amending your initial commit(s) to keep the history clean.

You can achieve this by using

See also :ref:`contributing` for how to make a PR.

.. note::

* If you have commit rights, then you are trusted to use them.

**Please help review and merge PRs!**

* Be patient and `kind <https://youtu.be/tzFWz5fiVKU?t=49m30s>`__ with

contributors.

.. _release_notes:

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::

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.

Before being merged, a PR should pass the :ref:`automated-tests`. If you are unsure why a test is failing, ask on the PR or in our `chat space <https://gitter.im/matplotlib/matplotlib>`_