Skip to content

Commit da123bc

Browse files
tacaswelltacaswell
authored
Merge pull request #23588 from melissawm/fix-gitwash
Refactoring gitwash
2 parents 0aac9f1 + 1b7510d commit da123bc

24 files changed

+216
-981
lines changed

‎doc/devel/coding_guide.rst

Lines changed: 86 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,92 @@
1313
Pull request guidelines
1414
***********************
1515

16-
Pull requests (PRs) are the mechanism for contributing to Matplotlibs code and
17-
documentation.
16+
`Pull requests (PRs) on GitHub
17+
<https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`__
18+
are the mechanism for contributing to Matplotlib's code and documentation.
19+
20+
It is recommended to check that your contribution complies with the following
21+
rules before submitting a pull request:
22+
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.
31+
32+
* Formatting should follow the recommendations of PEP8_, as enforced by
33+
flake8_. You can check flake8 compliance from the command line with ::
34+
35+
python -m pip install flake8
36+
flake8 /path/to/module.py
37+
38+
or your editor may provide integration with it. Note that Matplotlib
39+
intentionally does not use the black_ auto-formatter (1__), in particular due
40+
to its unability to understand the semantics of mathematical expressions
41+
(2__, 3__).
42+
43+
.. _PEP8: https://www.python.org/dev/peps/pep-0008/
44+
.. _flake8: https://flake8.pycqa.org/
45+
.. _black: https://black.readthedocs.io/
46+
.. __: https://github.com/matplotlib/matplotlib/issues/18796
47+
.. __: https://github.com/psf/black/issues/148
48+
.. __: https://github.com/psf/black/issues/1984
49+
50+
* All public methods should have informative docstrings with sample usage when
51+
appropriate. Use the :ref:`docstring standards <writing-docstrings>`.
52+
53+
* For high-level plotting functions, consider adding a simple example either in
54+
the ``Example`` section of the docstring or the
55+
:ref:`examples gallery <gallery>`.
56+
57+
* Changes (both new features and bugfixes) should have good test coverage. See
58+
:ref:`testing` for more details.
59+
60+
* Import the following modules using the standard scipy conventions::
61+
62+
import numpy as np
63+
import numpy.ma as ma
64+
import matplotlib as mpl
65+
import matplotlib.pyplot as plt
66+
import matplotlib.cbook as cbook
67+
import matplotlib.patches as mpatches
68+
69+
In general, Matplotlib modules should **not** import `.rcParams` using ``from
70+
matplotlib import rcParams``, but rather access it as ``mpl.rcParams``. This
71+
is because some modules are imported very early, before the `.rcParams`
72+
singleton is constructed.
73+
74+
* If your change is a major new feature, add an entry to the ``What's new``
75+
section by adding a new file in ``doc/users/next_whats_new`` (see
76+
:file:`doc/users/next_whats_new/README.rst` for more information).
77+
78+
* If you change the API in a backward-incompatible way, please document it in
79+
:file:`doc/api/next_api_changes/behavior`, by adding a new file with the
80+
naming convention ``99999-ABC.rst`` where the pull request number is followed
81+
by the contributor's initials. (see :file:`doc/api/api_changes.rst` for more
82+
information)
83+
84+
* See below for additional points about :ref:`keyword-argument-processing`, if
85+
applicable for your pull request.
86+
87+
.. note::
88+
89+
The current state of the Matplotlib code base is not compliant with all
90+
of these guidelines, but we expect that enforcing these constraints on all
91+
new contributions will move the overall code base quality in the right
92+
direction.
93+
94+
95+
.. seealso::
96+
97+
* :ref:`coding_guidelines`
98+
* :ref:`testing`
99+
* :ref:`documenting-matplotlib`
100+
101+
18102

19103
Summary for pull request authors
20104
================================

‎doc/devel/contributing.rst

Lines changed: 11 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,20 @@
44
Contributing
55
============
66

7+
You've discovered a bug or something else you want to change
8+
in Matplotlib — excellent!
9+
10+
You've worked out a way to fix it — even better!
11+
12+
You want to tell us about it — best of all!
13+
714
This project is a community effort, and everyone is welcome to
815
contribute. Everyone within the community
916
is expected to abide by our
1017
`code of conduct <https://github.com/matplotlib/matplotlib/blob/main/CODE_OF_CONDUCT.md>`_.
1118

12-
The project is hosted on
13-
https://github.com/matplotlib/matplotlib
19+
Below, you can find a number of ways to contribute, and how to connect with the
20+
Matplotlib community.
1421

1522
Get Connected
1623
=============
@@ -192,96 +199,8 @@ A brief overview is:
192199
Finally, go to the web page of your fork of the Matplotlib repo, and click
193200
'Pull request' to send your changes to the maintainers for review.
194201

195-
.. seealso::
196-
197-
* `Git documentation <https://git-scm.com/doc>`_
198-
* `Git-Contributing to a Project <https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project>`_
199-
* `Introduction to GitHub <https://lab.github.com/githubtraining/introduction-to-github>`_
200-
* :ref:`development-workflow` for best practices for Matplotlib
201-
* :ref:`using-git`
202-
203-
Contributing pull requests
204-
--------------------------
205-
206-
It is recommended to check that your contribution complies with the following
207-
rules before submitting a pull request:
208-
209-
* If your pull request addresses an issue, please use the title to describe the
210-
issue and mention the issue number in the pull request description to ensure
211-
that a link is created to the original issue.
212-
213-
* All public methods should have informative docstrings with sample usage when
214-
appropriate. Use the `numpy docstring standard
215-
<https://numpydoc.readthedocs.io/en/latest/format.html>`_.
216-
217-
* Formatting should follow the recommendations of PEP8_, as enforced by
218-
flake8_. You can check flake8 compliance from the command line with ::
219-
220-
python -m pip install flake8
221-
flake8 /path/to/module.py
222-
223-
or your editor may provide integration with it. Note that Matplotlib
224-
intentionally does not use the black_ auto-formatter (1__), in particular due
225-
to its inability to understand the semantics of mathematical expressions
226-
(2__, 3__).
227-
228-
.. _PEP8: https://www.python.org/dev/peps/pep-0008/
229-
.. _flake8: https://flake8.pycqa.org/
230-
.. _black: https://black.readthedocs.io/
231-
.. __: https://github.com/matplotlib/matplotlib/issues/18796
232-
.. __: https://github.com/psf/black/issues/148
233-
.. __: https://github.com/psf/black/issues/1984
234-
235-
* Each high-level plotting function should have a simple example in the
236-
``Example`` section of the docstring. This should be as simple as possible
237-
to demonstrate the method. More complex examples should go in the
238-
``examples`` tree.
239-
240-
* Changes (both new features and bugfixes) should have good test coverage. See
241-
:ref:`testing` for more details.
242-
243-
* Import the following modules using the standard scipy conventions::
244-
245-
import numpy as np
246-
import numpy.ma as ma
247-
import matplotlib as mpl
248-
import matplotlib.pyplot as plt
249-
import matplotlib.cbook as cbook
250-
import matplotlib.patches as mpatches
251-
252-
In general, Matplotlib modules should **not** import `.rcParams` using ``from
253-
matplotlib import rcParams``, but rather access it as ``mpl.rcParams``. This
254-
is because some modules are imported very early, before the `.rcParams`
255-
singleton is constructed.
256-
257-
* If your change is a major new feature, add an entry to the ``What's new``
258-
section by adding a new file in ``doc/users/next_whats_new`` (see
259-
:file:`doc/users/next_whats_new/README.rst` for more information).
260-
261-
* If you change the API in a backward-incompatible way, please document it in
262-
:file:`doc/api/next_api_changes/behavior`, by adding a new file with the
263-
naming convention ``99999-ABC.rst`` where the pull request number is followed
264-
by the contributor's initials. (see :file:`doc/api/api_changes.rst` for more
265-
information)
266-
267-
* See below for additional points about :ref:`keyword-argument-processing`, if
268-
applicable for your pull request.
269-
270-
.. note::
271-
272-
The current state of the Matplotlib code base is not compliant with all
273-
of those guidelines, but we expect that enforcing those constraints on all
274-
new contributions will move the overall code base quality in the right
275-
direction.
276-
277-
278-
.. seealso::
279-
280-
* :ref:`coding_guidelines`
281-
* :ref:`testing`
282-
* :ref:`documenting-matplotlib`
283-
284-
202+
For more detailed instructions on how to set up Matplotlib for development and
203+
best practices for contribution, see :ref:`installing_for_devs`.
285204

286205

287206
.. _contributing_documentation:

‎doc/devel/development_setup.rst

Lines changed: 38 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -9,38 +9,63 @@ To set up Matplotlib for development follow these steps:
99
.. contents::
1010
:local:
1111

12+
Fork the Matplotlib repository
13+
==============================
14+
15+
Matplotlib is hosted at https://github.com/matplotlib/matplotlib.git. If you
16+
plan on solving issues or submit pull requests to the main Matplotlib
17+
repository, you should first *fork* this repository by visiting
18+
https://github.com/matplotlib/matplotlib.git and clicking on the
19+
``Fork`` button on the top right of the page (see
20+
`the GitHub documentation <https://docs.github.com/get-started/quickstart/fork-a-repo>`__ for more details.)
21+
1222
Retrieve the latest version of the code
1323
=======================================
1424

15-
Matplotlib is hosted at https://github.com/matplotlib/matplotlib.git.
16-
17-
You can retrieve the latest sources with the command (see
18-
:ref:`set-up-fork` for more details)
25+
Now that your fork of the repository lives under your GitHub username, you can
26+
retrieve the latest sources with one of the following commands (where your
27+
should replace ``<your-username>`` with your GitHub username):
1928

2029
.. tab-set::
2130

2231
.. tab-item:: https
2332

2433
.. code-block:: bash
2534
26-
git clone https://github.com/matplotlib/matplotlib.git
35+
git clone https://github.com/<your-username>/matplotlib.git
2736
2837
.. tab-item:: ssh
2938

3039
.. code-block:: bash
3140
32-
git clone git@github.com:matplotlib/matplotlib.git
41+
git clone git@github.com:<your-username>/matplotlib.git
3342
3443
This requires you to setup an `SSH key`_ in advance, but saves you from
3544
typing your password at every connection.
3645

3746
.. _SSH key: https://docs.github.com/en/authentication/connecting-to-github-with-ssh
3847

48+
3949
This will place the sources in a directory :file:`matplotlib` below your
40-
current working directory. Change into this directory::
50+
current working directory, set up the ``origin`` remote to point to your own
51+
fork, and set up the ``upstream`` remote to point to the Matplotlib main
52+
repository (see also `Managing remote repositories <https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories>`__.)
53+
Change into this directory before continuing::
4154

4255
cd matplotlib
4356

57+
.. note::
58+
59+
For more information on ``git`` and ``GitHub``, check the following resources.
60+
61+
* `Git documentation <https://git-scm.com/doc>`_
62+
* `GitHub-Contributing to a Project <https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project>`_
63+
* `Introduction to GitHub <https://lab.github.com/githubtraining/introduction-to-github>`_
64+
* :ref:`using-git`
65+
* :ref:`git-resources`
66+
* `Installing git <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_
67+
* https://tacaswell.github.io/think-like-git.html
68+
* https://tom.preston-werner.com/2009/05/19/the-git-parable.html
4469

4570
.. _dev-environment:
4671

@@ -86,12 +111,8 @@ The simplest way to do this is to use either Python's virtual environment
86111

87112
Remember to activate the environment whenever you start working on Matplotlib.
88113

89-
Install additional development dependencies
90-
===========================================
91-
See :ref:`development-dependencies`.
92-
93-
Install Matplotlib in editable mode
94-
===================================
114+
Installing Matplotlib in editable mode
115+
======================================
95116
Install Matplotlib in editable mode from the :file:`matplotlib` directory
96117
using the command ::
97118

@@ -105,6 +126,10 @@ true for ``*.py`` files. If you change the C-extension source (which might
105126
also happen if you change branches) you will have to re-run
106127
``python -m pip install -ve .``
107128

129+
Install additional development dependencies
130+
===========================================
131+
See :ref:`development-dependencies`.
132+
108133
Install pre-commit hooks (optional)
109134
===================================
110135
`pre-commit <https://pre-commit.com/>`_ hooks automatically check flake8 and

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy