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 54d1197

Browse filesBrowse files
timhoffmtimhoffm
committed
Update PR guidelines
1 parent eb9b0d5 commit 54d1197
Copy full SHA for 54d1197

File tree

Expand file treeCollapse file tree

1 file changed

+137
-32
lines changed
Filter options
Expand file treeCollapse file tree

1 file changed

+137
-32
lines changed

‎doc/devel/coding_guide.rst

Copy file name to clipboardExpand all lines: doc/devel/coding_guide.rst
+137-32Lines changed: 137 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,76 @@
1-
.. _reviewers-guide:
1+
.. _pr-guidelines:
22

3-
********************
4-
Reviewers guideline
5-
********************
3+
***********************
4+
Pull request guidelines
5+
***********************
66

7-
.. _pull-request-checklist:
7+
Pull requests (PRs) are the mechanism for contributing to Matplotlibs code and
8+
documentation.
89

9-
Pull request checklist
10-
======================
10+
.. _pr-checklist-authors:
1111

12-
Branch selection
13-
----------------
12+
Checklist for PR authors
13+
========================
14+
15+
.. note::
16+
17+
* We value contributions from people with all levels of experience. In
18+
particular if this is your first PR not everything has to be perfect.
19+
We'll guide you through the PR process.
20+
* Nevertheless, try to follow the below guidelines as well as you can to
21+
help make the PR process quick and smooth.
22+
* Be patient with reviewers. We try our best to respond quickly, but we
23+
have limited bandwidth. If there is no feedback within a couple of days,
24+
please ping us by posting a comment to your PR.
25+
26+
When making a PR, pay attention to:
27+
28+
* :ref:`Target the master branch <pr-branch-selection>`.
29+
* Adhere to the :ref:`coding_guidelines`.
30+
* Update the :ref:`documentation <pr-documentation>` if necessary.
31+
* Aim at making the PR as "ready-to-go" as you can. This helps to speed up
32+
the review process.
33+
* It is ok to open incomplete or work-in-progress PRs if you need help or
34+
feedback from the developers. You may mark these as
35+
`draft pull requests <https://help.github.com/en/articles/about-pull-requests#draft-pull-requests>`_
36+
on GitHub.
37+
38+
See also :ref:`contributing` for how to make a PR.
39+
40+
.. _pr-checklist-reviewers:
41+
42+
Checklist for PR reviewers
43+
==========================
44+
.. note::
45+
46+
* If you have commit rights, then you are trusted to use them.
47+
**Please help review and merge PRs!**
48+
* Be patient and `kind <https://youtu.be/tzFWz5fiVKU?t=49m30s>`__ with
49+
contributors.
1450

15-
Generally, all pull requests (*PRs*) should target the master branch. Other
16-
branches are fed through automatic or manual backports. Directly targeting
17-
other branches is only rarely necessary for special maintenance work.
51+
Content topics:
52+
53+
* Is the feature / bugfix reasonable?
54+
* Does the PR conform with the :ref:`coding_guidelines`?
55+
* Is the :ref:`documentation <pr-documentation>` (docstrings, examples,
56+
what's new, API changes) updated?
57+
58+
Organizational topics:
59+
60+
* Make sure all :ref:`automated tests <pr-automated-tests>` pass.
61+
* The PR should :ref:`target the master branch <pr-branch-selection>`.
62+
* Tag with descriptive :ref:`labels <pr-labels>`.
63+
* Set the :ref:`milestone <pr-milestones>`.
64+
* Keep an eye on the :ref:`number of commits <pr-squashing>`.
65+
* Approve if all of the above topics handled.
66+
* :ref:`Merge <pr-merging>` if a sufficient number of approvals is reached.
67+
68+
.. _pr-guidelines-details:
69+
70+
Detailed Guidelines
71+
===================
72+
73+
.. _pr-documentation:
1874

1975
Documentation
2076
-------------
@@ -38,24 +94,25 @@ Documentation
3894
* If you change the API in a backward-incompatible way, please
3995
document it in :file:`doc/api/api_changes.rst`.
4096

41-
PR Review guidelines
42-
====================
43-
44-
* Be patient and `kind <https://youtu.be/tzFWz5fiVKU?t=49m30s>`__ with
45-
contributors.
97+
.. _pr-labels:
4698

47-
* If you have commit rights, then you are trusted to use them. Please
48-
help review and merge PRs!
99+
Labels
100+
------
49101

50102
* If you have the rights to set labels, tag the PR with descriptive labels.
51103
See the `list of labels <https://github.com/matplotlib/matplotlib/labels>`__.
52104

105+
.. _pr-milestones:
106+
107+
Milestones
108+
----------
109+
53110
* Set the milestone according to these rules:
54111

55-
* *New features and API changes* are milestoned for the next point-release
112+
* *New features and API changes* are milestoned for the next minor release
56113
``v3.X.0``.
57114

58-
* *Bugfixes and docstring changes* are milestoned for the next bugfix
115+
* *Bugfixes and docstring changes* are milestoned for the next patch
59116
release ``v3.X.Y``
60117

61118
* *Documentation changes* (all .rst files and examples) are milestoned
@@ -67,6 +124,11 @@ PR Review guidelines
67124
an :ref:`automatic backport <automated-backports>` for milestones which have
68125
a corresponding branch.
69126

127+
.. _pr-merging:
128+
129+
Merging
130+
-------
131+
70132
* Documentation and examples may be merged by the first reviewer. Use
71133
the threshold "is this better than it was?" as the review criteria.
72134

@@ -95,6 +157,11 @@ PR Review guidelines
95157
A core dev should only champion one PR at a time and we should try to keep
96158
the flow of championed PRs reasonable.
97159

160+
.. _pr-automated-tests:
161+
162+
Automated tests
163+
---------------
164+
98165
* Make sure the Travis, Appveyor, CircleCI, and codecov tests are passing
99166
before merging.
100167

@@ -107,6 +174,11 @@ PR Review guidelines
107174
when another reviewer explicitly allows it (ex, "Approve modulo CI
108175
passing, may self merge when green").
109176

177+
.. _pr-squashing:
178+
179+
Number of commits and squashing
180+
-------------------------------
181+
110182
* Squashing is case-by-case. The balance is between burden on the
111183
contributor, keeping a relatively clean history, and keeping a
112184
history usable for bisecting. The only time we are really strict
@@ -126,37 +198,68 @@ PR Review guidelines
126198
with the contributor first.
127199

128200

201+
.. _branches_and_backports:
202+
129203
Branches and Backports
130204
======================
131205

132-
206+
Current branches
207+
----------------
133208
The current active branches are
134209

135210
*master*
136-
This will be Matplotlib 3.0. Supports Python 3.5+.
211+
The current development version. Future minor releases (*v3.N.0*) will be
212+
branched from this. Supports Python 3.6+.
213+
214+
*v3.N.x*
215+
Maintenance branch for Matplotlib 3.N. Future patch releases will be
216+
branched from this. Supports Python 3.6+.
217+
218+
*v3.N.M-doc*
219+
Documentation for the current release. On a patch release, this will be
220+
replaced by a properly named branch for the new release.
137221

138222
*v2.2.x*
139-
Maintenance branch for Matplotlib 2.2 LTS. Supports Python 2.7, 3.4+
223+
Maintenance branch for Matplotlib 2.2 LTS. Supports Python 2.7, 3.4+.
140224

141225
*v2.2.N-doc*
142-
Documentation for the current release. On a patch release, this will be replaced
143-
by a properly named branch for the new release.
226+
Documentation for the current release. On a patch release, this will be
227+
replaced by a properly named branch for the new release.
228+
229+
230+
.. _pr-branch-selection:
231+
232+
Branch selection for pull requests
233+
----------------------------------
234+
235+
Generally, all pull requests should target the master branch.
144236

237+
Other branches are fed through :ref:`automatic <automated-backports>` or
238+
:ref:`manual <manual-backports>`. Directly
239+
targeting other branches is only rarely necessary for special maintenance
240+
work.
145241

146-
We always will backport to 2.2.x
242+
.. backport_strategy:
243+
244+
Backport strategy
245+
-----------------
246+
247+
We will always backport to the patch release branch (*v3.N.x*):
147248

148249
- critical bug fixes (segfault, failure to import, things that the
149250
user can not work around)
150-
- fixes for regressions against 2.0 or 2.1
251+
- fixes for regressions against the last two releases.
151252

152-
Everything else (regressions against 1.x versions, bugs/api
253+
Everything else (regressions against older releases, bugs/api
153254
inconsistencies the user can work around in their code) are on a
154255
case-by-case basis, should be low-risk, and need someone to advocate
155256
for and shepherd through the backport.
156257

157-
The only changes to be backported to 2.2.N-doc are changes to
158-
``doc``, ``examples``, or ``tutorials``. Any changes to
159-
``lib`` or ``src`` should not be backported to this branch.
258+
The only changes to be backported to the documentation branch (*v3.N.M-doc*)
259+
are changes to :file:`doc`, :file:`examples`, or :file:`tutorials`.
260+
Any changes to :file:`lib` or :file:`src` including docstring-only changes
261+
should not be backported to this branch.
262+
160263

161264
.. _automated-backports:
162265

@@ -178,6 +281,8 @@ If the bot is not working as expected, please report issues to
178281
`Meeseeksdev <https://github.com/MeeseeksBox/MeeseeksDev>`__.
179282

180283

284+
.. _manual-backports:
285+
181286
Manual backports
182287
----------------
183288

0 commit comments

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