8000 streamlined coding guide and added naming conventions table · matplotlib/matplotlib@6afa9bf · GitHub
[go: up one dir, main page]
Skip to content

Commit 6afa9bf

Browse files
story645story645
committed
streamlined coding guide and added naming conventions table
1 parent ca1880b commit 6afa9bf

File tree

7 files changed

+286
-215
lines changed

7 files changed

+286
-215
lines changed

‎doc/_static/mpl.css

Lines changed: 4 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -167,21 +167,7 @@ div.wide-table table th.stub {
167167
font-size: large;
168168
}
169169

170-
171-
.checklist {
172-
list-style: none;
173-
padding: 0;
174-
margin: 0;
175-
}
176-
.checklist li {
177-
margin-left: 24px;
178-
padding-left: 23px;
179-
margin-right: 6px;
180-
}
181-
.checklist li:before {
182-
content: "\2610\2001";
183-
margin-left: -24px;
184-
}
185-
.checklist li p {
186-
display: inline;
187-
}
170+
.checklist { list-style: none; padding: 0; margin: 0; }
171+
.checklist li { margin-left: 24px; padding-left: 23px; margin-right: 6px; }
172+
.checklist li:before { content: "\2610\2001"; margin-left: -24px; }
173+
.checklist li p {display: inline; }

‎doc/api/next_api_changes/README.rst

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,17 @@ author's initials. Typically, each change will get its own file, but you may
2222
also amend existing files when suitable. The overall goal is a comprehensible
2323
documentation of the changes.
2424

25-
Please avoid using references in section titles, as it causes links to be
26-
confusing in the table of contents. Instead, ensure that a reference is
27-
included in the descriptive text. A typical entry could look like this::
25+
A typical entry could look like this: ::
2826

2927
Locators
3028
~~~~~~~~
3129
The unused `Locator.autoscale()` method is deprecated (pass the axis
3230
limits to `Locator.view_limits()` instead).
31+
32+
Please avoid using references in section titles, as it causes links to be
33+
confusing in the table of contents. Instead, ensure that a reference is
34+
included in the descriptive text.
35+
36+
.. NOTE
37+
Lines 5-30 of this file are include in :ref:`api_whats_new`;
38+
therefore, please check the doc build after changing this file.

‎doc/devel/coding_guide.rst

Lines changed: 47 additions & 164 deletions
Original file line numberDiff line numberDiff line change
@@ -8,144 +8,82 @@ Pull request guidelines
88
<https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`__
99
are the mechanism for contributing to Matplotlib's code and documentation.
1010

11-
It is recommended to check that your contribution complies with the following
12-
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.
1317

14-
* If your pull request addresses an issue, please use the title to describe the
15-
issue (e.g. "Add ability to plot timedeltas") and mention the issue number
16-
in the pull request description to ensure that a link is created to the
17-
original issue (e.g. "Closes #8869" or "Fixes #8869"). This will ensure the
18-
original issue mentioned is automatically closed when your PR is merged. See
19-
`the GitHub documentation
20-
<https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue>`__
21-
for more details.
22-
23-
* Formatting should follow the recommendations of PEP8_, as enforced by
24-
flake8_. Matplotlib modifies PEP8 to extend the maximum line length to 88
25-
characters. You can check flake8 compliance from the command line with ::
26-
27-
python -m pip install flake8
28-
flake8 /path/to/module.py
29-
30-
or your editor may provide integration with it. Note that Matplotlib
31-
intentionally does not use the black_ auto-formatter (1__), in particular due
32-
to its inability to understand the semantics of mathematical expressions
33-
(2__, 3__).
34-
35-
.. _PEP8: https://www.python.org/dev/peps/pep-0008/
36-
.. _flake8: https://flake8.pycqa.org/
37-
.. _black: https://black.readthedocs.io/
38-
.. __: https://github.com/matplotlib/matplotlib/issues/18796
39-
.. __: https://github.com/psf/black/issues/148
40-
.. __: https://github.com/psf/black/issues/1984
41-
42-
* All public methods should have informative docstrings with sample usage when
43-
appropriate. Use the :ref:`docstring standards <writing-docstrings>`.
44-
45-
* For high-level plotting functions, consider adding a simple example either in
46-
the ``Example`` section of the docstring or the
47-
:ref:`examples gallery <gallery>`.
48-
49-
* Changes (both new features and bugfixes) should have good test coverage. See
50-
:ref:`testing` for more details.
51-
52-
* Import the following modules using the standard scipy conventions::
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.
5321

54-
import numpy as np
55-
import numpy.ma as ma
56-
import matplotlib as mpl
57-
import matplotlib.pyplot as plt
58-
import matplotlib.cbook as cbook
59-
import matplotlib.patches as mpatches
6022

61-
In general, Matplotlib modules should **not** import `.rcParams` using ``from
62-
matplotlib import rcParams``, but rather access it as ``mpl.rcParams``. This
63-
is because some modules are imported very early, before the `.rcParams`
64-
singleton is constructed.
65-
66-
* If your change is a major new feature, add an entry to the ``What's new``
67-
section by adding a new file in ``doc/users/next_whats_new`` (see
68-
:file:`doc/users/next_whats_new/README.rst` for more information).
23+
Summary for pull request authors
24+
================================
6925

70-
* If you change the API in a backward-incompatible way, please document it in
71-
:file:`doc/api/next_api_changes/behavior`, by adding a new file with the
72-
naming convention ``99999-ABC.rst`` where the pull request number is followed
73-
by the contributor's initials. (see :file:`doc/api/api_changes.rst` for more
74-
information)
26+
We recommend that you check that your contribution complies with the following
27+
guidelines before submitting a pull request:
7528

76-
* If you add new public API or change public API, update or add the
77-
corresponding type hints. Most often this is found in the corresponding
78-
``.pyi`` file for the ``.py`` file which was edited. Changes in ``pyplot.py``
79-
are type hinted inline.
29+
.. rst-class:: checklist
8030

81-
* See below for additional points about :ref:`keyword-argument-processing`, if
82-
applicable for your pull request.
31+
* Changes, both new features and bugfixes, should have good test coverage. See
32+
:ref:`testing` for more details.
8333

84-
.. note::
34+
* Update the :ref:`documentation <pr-documentation>` if necessary.
8535

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

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

92-
.. 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:`new-changed-api`
9344

94-
* :ref:`coding_guidelines`
95-
* :ref:`testing`
96-
* :ref:`documenting-matplotlib`
45+
* Code should follow our conventions as documented in our :ref:`coding_guidelines`
9746

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

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

100-
Summary for pull request authors
101-
================================
51+
When opening a pull request on Github, please ensure that:
10252

103-
.. note::
53+
.. rst-class:: checklist
10454

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

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

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

118-
* :ref:`Target the main branch <pr-branch-selection>`.
119-
* Adhere to the :ref:`coding_guidelines`.
120-
* Update the :ref:`documentation <pr-documentation>` if necessary.
121-
* Aim at making the PR as "ready-to-go" as you can. This helps to speed up
122-
the review process.
123-
* It is ok to open incomplete or work-in-progress PRs if you need help or
124-
feedback from the developers. You may mark these as
125-
`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>`_
126-
on GitHub.
127-
* When updating your PR, instead of adding new commits to fix something, please
128-
consider amending your initial commit(s) to keep the history clean.
129-
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>`__.
13067

131-
.. code-block:: bash
68+
* :ref:`pr-automated-tests` pass
13269

133-
git commit --amend --no-edit
134-
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.
13573

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

13875
Summary for pull request reviewers
13976
==================================
14077

14178
.. redirect-from:: /devel/maintainer_workflow
14279

143-
.. note::
80+
**Please help review and merge PRs!**
81+
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.
14484

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

15088
Content topics:
15189

@@ -196,61 +134,6 @@ Documentation
196134

197135
* See :ref:`documenting-matplotlib` for our documentation style guide.
198136

199-
.. _release_notes:
200-
201-
New features and API changes
202-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
203-
When adding a major new feature or changing the API in a backward incompatible
204-
way, please document it by including a versioning directive in the docstring
205-
and adding an entry to the folder for either the what's new or API change notes.
206-
207-
+-------------------+-----------------------------+----------------------------------+
208-
| for this addition | include this directive | create entry in this folder |
209-
+===================+=============================+==================================+
210-
| new feature | ``.. versionadded:: 3.N`` | :file:`doc/users/next_whats_new/`|
211-
+-------------------+-----------------------------+----------------------------------+
212-
| API change | ``.. versionchanged:: 3.N`` | :file:`doc/api/next_api_changes/`|
213-
| | | |
214-
| | | probably in ``behavior/`` |
215-
+-------------------+-----------------------------+----------------------------------+
216-
217-
The directives should be placed at the end of a description block. For example::
218-
219-
class Foo:
220-
"""
221-
This is the summary.
222-
223-
Followed by a longer description block.
224-
225-
Consisting of multiple lines and paragraphs.
226-
227-
.. versionadded:: 3.5
228-
229-
Parameters
230-
----------
231-
a : int
232-
The first parameter.
233-
b: bool, default: False
234-
This was added later.
235-
236-
.. versionadded:: 3.6
237-
"""
238-
239-
def set_b(b):
240-
"""
241-
Set b.
242-
243-
.. versionadded:: 3.6
244-
245-
Parameters
246-
----------
247-
b: bool
248-
249-
For classes and functions, the directive should be placed before the
250-
*Parameters* section. For parameters, the directive should be placed at the
251-
end of the parameter description. The patch release version is omitted and
252-
the directive should not be added to entire modules.
253-
254137
.. _pr-labels:
255138

256139
Labels

0 commit comments

Comments
 (0)
0