Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 4a4496a

Browse filesBrowse files
story645story645
committed
streamlined coding guide and added naming conventions table
1 parent 309981d commit 4a4496a
Copy full SHA for 4a4496a

File tree

4 files changed

+157
-118
lines changed
Filter options

4 files changed

+157
-118
lines changed

‎doc/_static/mpl.css

Copy file name to clipboardExpand all lines: doc/_static/mpl.css
+5Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,3 +161,8 @@ div.wide-table table th.stub {
161161
font-style: italic;
162162
font-size: large;
163163
}
164+
165+
.checklist { list-style: none; padding: 0; margin: 0; }
166+
.checklist li { margin-left: 24px; padding-left: 23px; margin-right: 6px; }
167+
.checklist li:before { content: "\2610\2001"; margin-left: -24px; }
168+
.checklist li p {display: inline; }

‎doc/devel/coding_guide.rst

Copy file name to clipboardExpand all lines: doc/devel/coding_guide.rst
+133-118Lines changed: 133 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,3 @@
1-
.. raw:: html
2-
3-
<style>
4-
.checklist { list-style: none; padding: 0; margin: 0; }
5-
.checklist li { margin-left: 24px; padding-left: 23px; margin-right: 6px; }
6-
.checklist li:before { content: "\2610\2001"; margin-left: -24px; }
7-
.checklist li p {display: inline; }
8-
</style>
9-
101
.. _pr-guidelines:
112

123
***********************
@@ -17,144 +8,82 @@ Pull request guidelines
178
<https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`__
189
are the mechanism for contributing to Matplotlib's code and documentation.
1910

20-
It is recommended to check that your contribution complies with the following
21-
rules before submitting a pull request:
11+
We value contributions from people with all levels of experience. In particular,
12+
if this is your first PR not everything has to be perfect. We'll guide you
13+
through the PR process. Nevertheless, please try to follow our guidelines as well
14+
as you can to help make the PR process quick and smooth. If your pull request is
15+
incomplete or a work-in-progress, please mark it as a `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>`_
16+
on GitHub and specify what feedback from the developers would be helpful.
2217

23-
* If your pull request addresses an issue, please use the title to describe the
24-
issue (e.g. "Add ability to plot timedeltas") and mention the issue number
25-
in the pull request description to ensure that a link is created to the
26-
original issue (e.g. "Closes #8869" or "Fixes #8869"). This will ensure the
27-
original issue mentioned is automatically closed when your PR is merged. See
28-
`the GitHub documentation
29-
<https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue>`__
30-
for more details.
18+
Please be patient with reviewers. We try our best to respond quickly, but we have
19+
limited bandwidth. If there is no feedback within a couple of days, please ping
20+
us by posting a comment to your PR.
3121

32-
* Formatting should follow the recommendations of PEP8_, as enforced by
33-
flake8_. Matplotlib modifies PEP8 to extend the maximum line length to 88
34-
characters. You can check flake8 compliance from the command line with ::
3522

36-
python -m pip install flake8
37-
flake8 /path/to/module.py
38-
39-
or your editor may provide integration with it. Note that Matplotlib
40-
intentionally does not use the black_ auto-formatter (1__), in particular due
41-
to its inability to understand the semantics of mathematical expressions
42-
(2__, 3__).
23+
Summary for pull request authors
24+
================================
4325

44-
.. _PEP8: https://www.python.org/dev/peps/pep-0008/
45-
.. _flake8: https://flake8.pycqa.org/
46-
.. _black: https://black.readthedocs.io/
47-
.. __: https://github.com/matplotlib/matplotlib/issues/18796
48-
.. __: https://github.com/psf/black/issues/148
49-
.. __: https://github.com/psf/black/issues/1984
26+
We recommend that you check that your contribution complies with the following
27+
guidelines before submitting a pull request:
5028

51-
* All public methods should have informative docstrings with sample usage when
52-
appropriate. Use the :ref:`docstring standards <writing-docstrings>`.
53-
54-
* For high-level plotting functions, consider adding a simple example either in
55-
the ``Example`` section of the docstring or the
56-
:ref:`examples gallery <gallery>`.
29+
.. rst-class:: checklist
5730

58-
* Changes (both new features and bugfixes) should have good test coverage. See
31+
* Changes, both new features and bugfixes, should have good test coverage. See
5932
:ref:`testing` for more details.
6033

61-
* Import the following modules using the standard scipy conventions::
62-
63-
import numpy as np
64-
import numpy.ma as ma
65-
import matplotlib as mpl
66-
import matplotlib.pyplot as plt
67-
import matplotlib.cbook as cbook
68-
import matplotlib.patches as mpatches
69-
70-
In general, Matplotlib modules should **not** import `.rcParams` using ``from
71-
matplotlib import rcParams``, but rather access it as ``mpl.rcParams``. This
72-
is because some modules are imported very early, before the `.rcParams`
73-
singleton is constructed.
74-
75-
* If your change is a major new feature, add an entry to the ``What's new``
76-
section by adding a new file in ``doc/users/next_whats_new`` (see
77-
:file:`doc/users/next_whats_new/README.rst` for more information).
78-
79-
* If you change the API in a backward-incompatible way, please document it in
80-
:file:`doc/api/next_api_changes/behavior`, by adding a new file with the
81-
naming convention ``99999-ABC.rst`` where the pull request number is followed
82-
by the contributor's initials. (see :file:`doc/api/api_changes.rst` for more
83-
information)
84-
85-
* If you add new public API or change public API, update or add the
86-
corresponding type hints. Most often this is found in the corresponding
87-
``.pyi`` file for the ``.py`` file which was edited. Changes in ``pyplot.py``
88-
are type hinted inline.
89-
90-
* See below for additional points about :ref:`keyword-argument-processing`, if
91-
applicable for your pull request.
92-
93-
.. note::
34+
* Update the :ref:`documentation <pr-documentation>` if necessary.
9435

95-
The current state of the Matplotlib code base is not compliant with all
96-
of these guidelines, but we expect that enforcing these constraints on all
97-
new contributions will move the overall code base quality in the right
98-
direction.
36+
* All public methods should have informative docstrings with sample usage when
37+
appropriate. Use the :ref:`docstring standards <writing-docstrings>`.
9938

39+
* For high-level plotting functions, consider adding a small example to the
40+
:ref:`examples gallery <gallery>`.
10041

101-
.. seealso::
42+
* If you add a major new feature or change the API in a backward-incompatible
43+
way, please document it as described in :ref:`api_whats_new`
10244

103-
* :ref:`coding_guidelines`
104-
* :ref:`testing`
105-
* :ref:`documenting-matplotlib`
45+
* Code should follow our conventions as documented in our :ref:`coding-standards`
10646

47+
* When adding or changing public function signatures, add :ref:`type hints <type-hints>`
10748

49+
* When adding keyword arguments, see our guide to :ref:`keyword-argument-processing`.
10850

109-
Summary for pull request authors
110-
================================
51+
When opening a pull request on Github, please ensure that:
11152

112-
.. note::
53+
.. rst-class:: checklist
11354

114-
* We value contributions from people with all levels of experience. In
115-
particular if this is your first PR not everything has to be perfect.
116-
We'll guide you through the PR process.
117-
* Nevertheless, please try to follow the guidelines below as well as you can to
118-
help make the PR process quick and smooth.
119-
* Be patient with reviewers. We try our best to respond quickly, but we
120-
have limited bandwidth. If there is no feedback within a couple of days,
121-
please ping us by posting a comment to your PR.
55+
* Changes were made on a :ref:`feature branch <make-feature-branch>`.
12256

123-
When making a PR, pay attention to:
57+
* :ref:`pre-commit <pre-commit-hooks>` checks for spelling, formatting, etc pass
12458

125-
.. rst-class:: checklist
59+
* The pull request targets the :ref:`main branch <pr-branch-selection>`
12660

127-
* :ref:`Target the main branch <pr-branch-selection>`.
128-
* Adhere to the :ref:`coding_guidelines`.
129-
* Update the :ref:`documentation <pr-documentation>` if necessary.
130-
* Aim at making the PR as "ready-to-go" as you can. This helps to speed up
131-
the review process.
132-
* It is ok to open incomplete or work-in-progress PRs if you need help or
133-
feedback from the developers. You may mark these as
134-
`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>`_
135-
on GitHub.
136-
* When updating your PR, instead of adding new commits to fix something, please
137-
consider amending your initial commit(s) to keep the history clean.
138-
You can achieve this by using
61+
* If your pull request addresses an issue, please use the title to describe the
62+
issue (e.g. "Add ability to plot timedeltas") and mention the issue number
63+
in the pull request description to ensure that a link is created to the
64+
original issue (e.g. "Closes #8869" or "Fixes #8869"). This will ensure the
65+
original issue mentioned is automatically closed when your PR is merged. For more
66+
details, see `linking an issue and pull request <https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue>`__.
13967

140-
.. code-block:: bash
68+
* :ref:`pr-automated-tests` pass
14169

142-
git commit --amend --no-edit
143-
git push [your-remote-repo] [your-branch] --force-with-lease
70+
For guidance on creating and managing a pull request, please see our
71+
:ref:`contributing <contributing>` and :ref:`pull request workflow <edit-flow>`
72+
guides.
14473

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

14775
Summary for pull request reviewers
14876
==================================
14977

15078
.. redirect-from:: /devel/maintainer_workflow
15179

152-
.. note::
80+
**Please help review and merge PRs!**
15381

154-
* If you have commit rights, then you are trusted to use them.
155-
**Please help review and merge PRs!**
156-
* Be patient and `kind <https://youtu.be/tzFWz5fiVKU?t=49m30s>`__ with
157-
contributors.
82+
If you have commit rights, then you are trusted to use them. Please be patient
83+
and `kind <https://youtu.be/tzFWz5fiVKU?t=49m30s>`__ with contributors.
84+
85+
When reviewing, please ensure that the pull request satisfies the following
86+
requirements before merging it:
15887

15988
Content topics:
16089

@@ -187,6 +116,88 @@ Organizational topics:
187116
Detailed guidelines
188117
===================
189118

119+
.. _coding-standards:
120+
121+
Coding style guide
122+
------------------
123+
124+
While the current state of the Matplotlib code base is not compliant with all
125+
of these guidelines, but our goal in enforcing these constraints on new
126+
contributions is that it improves the readability and consistency of the code base
127+
going forward.
128+
129+
PEP8, as enforced by flake8
130+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
131+
132+
Formatting should follow the recommendations of PEP8_, as enforced by flake8_.
133+
Matplotlib modifies PEP8 to extend the maximum line length to 88
134+
characters. You can check flake8 compliance from the command line with ::
135+
136+
python -m pip install flake8
137+
flake8 /path/to/module.py
138+
139+
or your editor may provide integration with it. Note that Matplotlib intentionally
140+
does not use the black_ auto-formatter (1__), in particular due to its inability
141+
to understand the semantics of mathematical expressions (2__, 3__).
142+
143+
.. _PEP8: https://www.python.org/dev/peps/pep-0008/
144+
.. _flake8: https://flake8.pycqa.org/
145+
.. _black: https://black.readthedocs.io/
146+
.. __: https://github.com/matplotlib/matplotlib/issues/18796
147+
.. __: https://github.com/psf/black/issues/148
148+
.. __: https://github.com/psf/black/issues/1984
149+
150+
151+
Package imports
152+
^^^^^^^^^^^^^^^
153+
Import the following modules using the standard scipy conventions::
154+
155+
import numpy as np
156+
import numpy.ma as ma
157+
import matplotlib as mpl
158+
import matplotlib.pyplot as plt
159+
import matplotlib.cbook as cbook
160+
import matplotlib.patches as mpatches
161+
162+
In general, Matplotlib modules should **not** import `.rcParams` using ``from
163+
matplotlib import rcParams``, but rather access it as ``mpl.rcParams``. This
164+
is because some modules are imported very early, before the `.rcParams`
165+
singleton is constructed.
166+
167+
Naming variables
168+
^^^^^^^^^^^^^^^^
169+
When feasible, please use our internal variable naming convention for objects
170+
of a given class and objects of any child class:
171+
172+
+---------------+------------------------------------+
173+
| variable name | base class |
174+
+===============+====================================+
175+
| ``fig`` | `~matplotlib.figure.FigureBase` |
176+
+---------------+------------------------------------+
177+
| ``ax`` | `~matplotlib.axes.Axes` |
178+
+---------------+------------------------------------+
179+
| ``trans`` | `~matplotlib.transforms.Transform` |
180+
+---------------+------------------------------------+
181+
182+
Generally, denote more than instance of the same class by adding numbers to
183+
the variable names, i.e. ``trans1``, ``trans2``.
184+
185+
.. _type-hints:
186+
187+
Type hints
188+
^^^^^^^^^^
189+
190+
If you add new public API or change public API, update or add the
191+
corresponding `mypy <https://mypy.readthedocs.io/en/latest/>`_ type hints.
192+
Most often this is found in the corresponding ``.pyi`` file for the edited
193+
``.py`` file, for example ``colors.py`` and ``colors.pyi``. Changes in ``pyplot.py``
194+
are type hinted inline.
195+
196+
Type hints are checked by the mypy :ref:`pre-commit hook <pre-commit-hooks>`
197+
and can often be verified using ``tools\stubtest.py`` and occasionally may
198+
require the use of ``tools\check_typehints.py``.
199+
200+
190201
.. _pr-documentation:
191202

192203
Documentation
@@ -205,7 +216,7 @@ Documentation
205216

206217
* See :ref:`documenting-matplotlib` for our documentation style guide.
207218

208-
.. _release_notes:
219+
.. _api_whats_new:
209220

210221
New features and API changes
211222
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -223,6 +234,10 @@ and adding an entry to the folder for either the what's new or API change notes.
223234
| | | probably in ``behavior/`` |
224235
+-------------------+-----------------------------+----------------------------------+
225236

237+
The API change note should be named ``99999-ABC.rst`` where the pull request
238+
number is followed by the contributor's initials. For more information, see
239+
:file:`doc/api/api_changes.rst` and :file:`doc/users/next_whats_new/README.rst`.
240+
226241
The directives should be placed at the end of a description block. For example::
227242

228243
class Foo:

‎doc/devel/development_setup.rst

Copy file name to clipboardExpand all lines: doc/devel/development_setup.rst
+2Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -203,6 +203,8 @@ you are aware of the existing issues beforehand.
203203
* Run test cases to verify installation :ref:`testing`
204204
* Verify documentation build :ref:`documenting-matplotlib`
205205

206+
.. _pre-commit-hooks:
207+
206208
Install pre-commit hooks
207209
========================
208210
`pre-commit <https://pre-commit.com/>`_ hooks save time in the review process by

‎doc/devel/development_workflow.rst

Copy file name to clipboardExpand all lines: doc/devel/development_workflow.rst
+17Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,23 @@ If you don't think your request is ready to be merged, just say so in your pull
151151
request message and use the "Draft PR" feature of GitHub. This is a good way of
152152
getting some preliminary code review.
153153

154+
.. _update-pull-request:
155+
156+
Update a pull request
157+
=====================
158+
159+
When updating your pull request after making revisions, instead of adding new
160+
commits, please consider amending your initial commit(s) to keep the commit
161+
history clean.
162+
163+
You can achieve this by using
164+
165+
.. code-block:: bash
166+
167+
git commit -a --amend --no-edit
168+
git push [your-remote-repo] [your-branch] --force-with-lease
169+
170+
154171
Manage commit history
155172
=====================
156173

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.