8000 Merge pull request #23588 from melissawm/fix-gitwash · matplotlib/matplotlib@da123bc · GitHub
[go: up one dir, main page]
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)
0