8000 Merge pull request #29048 from story645/contrib-shuffle · matplotlib/matplotlib@773096e · GitHub
[go: up one dir, main page]
Skip to content

Commit 773096e

Browse files
timhoffmtimhoffm
authored
Merge pull request #29048 from story645/contrib-shuffle
DOC: integrated pr workflow from contributing guide into install and workflow
2 parents 825dbe9 + 386032d commit 773096e

File tree

4 files changed

+106
-120
lines changed

4 files changed

+106
-120
lines changed

‎doc/devel/contribute.rst

Lines changed: 11 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -319,113 +319,19 @@ Start a pull request
319319

320320
The preferred way to contribute to Matplotlib is to fork the `main
321321
repository <https://github.com/matplotlib/matplotlib/>`__ on GitHub,
322-
then submit a "pull request" (PR). You can do this by cloning a copy of the
323-
Matplotlib repository to your own computer, or alternatively using
324-
`GitHub Codespaces <https://docs.github.com/codespaces>`_, a cloud-based
325-
in-browser development environment that comes with the appropriate setup to
326-
contribute to Matplotlib.
322+
then submit a "pull request" (PR). To work on a a pull request:
327323

328-
Workflow overview
329-
-----------------
330-
331-
A brief overview of the workflow is as follows.
332-
333-
#. `Create an account <https://github.com/join>`_ on GitHub if you do not
334-
already have one.
335-
336-
#. Fork the `project repository <https://github.com/matplotlib/matplotlib>`_ by
337-
clicking on the :octicon:`repo-forked` **Fork** button near the top of the page.
338-
This creates a copy of the code under your account on the GitHub server.
339-
340-
#. Set up a development environment:
341-
342-
.. tab-set::
343-
344-
.. tab-item:: Local development
345-
346-
Clone this copy to your local disk::
347-
348-
git clone https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git
349-
350-
.. tab-item:: Using GitHub Codespaces
351-
352-
Check out the Matplotlib repository and activate your development environment:
353-
354-
#. Open codespaces on your fork by clicking on the green "Code" button
355-
on the GitHub web interface and selecting the "Codespaces" tab.
356-
357-
#. Next, click on "Open codespaces on <your branch name>". You will be
358-
able to change branches later, so you can select the default
359-
``main`` branch.
360-
361-
#. After the codespace is created, you will be taken to a new browser
362-
tab where you can use the terminal to activate a pre-defined conda
363-
environment called ``mpl-dev``::
364-
365-
conda activate mpl-dev
366-
367-
368-
#. Install the local version of Matplotlib with::
369-
370-
python -m pip install --no-build-isolation --editable .[dev]
371-
372-
See :ref:`installing_for_devs` for detailed instructions.
373-
374-
#. Create a branch to hold your changes::
375-
376-
git checkout -b my-feature origin/main
377-
378-
and start making changes. Never work in the ``main`` branch!
379-
380-
#. Work on this task using Git to do the version control. Codespaces persist for
381-
some time (check the `documentation for details
382-
<https://docs.github.com/codespaces/getting-started/the-codespace-lifecycle>`_)
383-
and can be managed on https://github.com/codespaces. When you're done editing
384-
e.g., ``lib/matplotlib/collections.py``, do::
385-
386-
git add lib/matplotlib/collections.py
387-
git commit -m 'a commit message'
388-
389-
to record your changes in Git, then push them to your GitHub fork with::
390-
391-
git push -u origin my-feature
392-
393-
GitHub Codespaces workflows
394-
"""""""""""""""""""""""""""
395-
396-
If you need to open a GUI window with Matplotlib output on Codespaces, our
397-
configuration includes a `light-weight Fluxbox-based desktop
398-
<https://github.com/devcontainers/features/tree/main/src/desktop-lite>`_.
399-
You can use it by connecting to this desktop via your web browser. To do this:
400-
401-
#. Press ``F1`` or ``Ctrl/Cmd+Shift+P`` and select
402-
``Ports: Focus on Ports View`` in the VSCode session to bring it into
403-
focus. Open the ports view in your tool, select the ``noVNC`` port, and
404-
click the Globe icon.
405-
#. In the browser that appears, click the Connect button and enter the desktop
406-
password (``vscode`` by default).
407-
408-
Check the `GitHub instructions
409-
<https://github.com/devcontainers/features/tree/main/src/desktop-lite#connecting-to-the-desktop>`_
410-
for more details on connecting to the desktop.
411-
412-
View documentation
413-
''''''''''''''''''
324+
#. **First** set up a development environment, either by cloning a copy of the
325+
Matplotlib repository to your own computer or by using Github codespaces, by
326+
following the instructions in :ref:`installing_for_devs`
414327

415-
If you also built the documentation pages, you can view them using Codespaces.
416-
Use the "Extensions" icon in the activity bar to install the "Live Server"
417-
extension. Locate the ``doc/build/html`` folder in the Explorer, right click
418-
the file you want to open and select "Open with Live Server."
328+
#. **Then** start a pull request by following the guidance in :ref:`development workflow <development-workflow>`
419329

420-
Open a pull request on Matplotlib
421-
---------------------------------
330+
#. **After starting** check that your contribution meets the :ref:`pull request guidelines <pr-author-guidelines>`
331+
and :ref:`update the pull request <update-pull-request>` as needed.
422332

423-
Finally, go to the web page of *your fork* of the Matplotlib repo, and click
424-
**Compare & pull request** to send your changes to the maintainers for review.
425-
The base repository is ``matplotlib/matplotlib`` and the base branch is
426-
generally ``main``. For more guidance, see GitHub's `pull request tutorial
427-
<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_.
333+
#. **Finally** follow up with maintainers on the PR if waiting more than a few days for
334+
feedback.
428335

429-
For more detailed instructions on how to set up Matplotlib for development and
430-
best practices for contribution, see :ref:`installing_for_devs` and
431-
:ref:`development-workflow`.
336+
If you have questions of any sort, reach out on the :ref:`contributor_incubator` and join
337+
the :ref:`new_contributors_meeting`.

‎doc/devel/development_setup.rst

Lines changed: 58 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,11 @@ Fork the Matplotlib repository
2828

2929
Matplotlib is hosted at https://github.com/matplotlib/matplotlib.git. If you
3030
plan on solving issues or submitting pull requests to the main Matplotlib
31-
repository, you should first *fork* this repository by visiting
32-
https://github.com/matplotlib/matplotlib.git and clicking on the
33-
``Fork`` :octicon:`repo-forked` button on the top right of the page. See
34-
`the GitHub documentation <https://docs.github.com/get-started/quickstart/fork-a-repo>`__
35-
for more details.
31+
repository, you should first fork this repository by *clicking* the
32+
:octicon:`repo-forked` **Fork** button near the top of the `project repository <https://github.com/matplotlib/matplotlib>`_ page.
33+
34+
This creates a copy of the code under your account on the GitHub server. See `the GitHub
35+
documentation <https://docs.github.com/get-started/quickstart/fork-a-repo>`__ for more details.
3636

3737
Retrieve the latest version of the code
3838
=======================================
@@ -111,8 +111,9 @@ Create a dedicated environment
111111
You should set up a dedicated environment to decouple your Matplotlib
112112
development from other Python and Matplotlib installations on your system.
113113

114-
The simplest way to do this is to use either Python's virtual environment
115-
`venv`_ or `conda`_.
114+
We recommend using one of the following options for a dedicated development environment
115+
because these options are configured to install the Python dependencies as part of their
116+
setup.
116117

117118
.. _venv: https://docs.python.org/3/library/venv.html
118119
.. _conda: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html
@@ -138,6 +139,8 @@ The simplest way to do this is to use either Python's virtual environment
138139

139140
pip install -r requirements/dev/dev-requirements.txt
140141

142+
Remember to activate the environment whenever you start working on Matplotlib!
143+
141144
.. tab-item:: conda environment
142145

143146
Create a new `conda`_ environment and install the Python dependencies with ::
@@ -153,21 +156,66 @@ The simplest way to do this is to use either Python's virtual environment
153156

154157
conda activate mpl-dev
155158

156-
Remember to activate the environment whenever you start working on Matplotlib.
159+
Remember to activate the environment whenever you start working on Matplotlib!
160+
161+
.. tab-item:: :octicon:`codespaces` GitHub Codespaces
162+
163+
`GitHub Codespaces <https://docs.github.com/codespaces>`_ is a cloud-based
164+
in-browser development environment that comes with the appropriate setup to
165+
contribute to Matplotlib.
166+
167+
#. Open codespaces on your fork by clicking on the green :octicon:`code` ``Code``
168+
button on the GitHub web interface and selecting the ``Codespaces`` tab.
169+
170+
#. Next, click on "Open codespaces on <your branch name>". You will be
171+
able to change branches later, so you can select the default
172+
``main`` branch.
173+
174+
#. After the codespace is created, you will be taken to a new browser
175+
tab where you can use the terminal to activate a pre-defined conda
176+
environment called ``mpl-dev``::
177+
178+
conda activate mpl-dev
179+
180+
Remember to activate the *mpl-dev* environment whenever you start working on
181+
Matplotlib.
182+
183+
If you need to open a GUI window with Matplotlib output on Codespaces, our
184+
configuration includes a `light-weight Fluxbox-based desktop
185+
<https://github.com/devcontainers/features/tree/main/src/desktop-lite>`_.
186+
You can use it by connecting to this desktop via your web browser. To do this:
187+
188+
#. Press ``F1`` or ``Ctrl/Cmd+Shift+P`` and select
189+
``Ports: Focus on Ports View`` in the VSCode session to bring it into
190+
focus. Open the ports view in your tool, select the ``noVNC`` port, and
191+
click the Globe icon.
192+
#. In the browser that appears, click the Connect button and enter the desktop
193+
password (``vscode`` by default).
194+
195+
Check the `GitHub instructions
196+
<https://github.com/devcontainers/features/tree/main/src/desktop-lite#connecting-to-the-desktop>`_
197+
for more details on connecting to the desktop.
198+
199+
If you also built the documentation pages, you can view them using Codespaces.
200+
Use the "Extensions" icon in the activity bar to install the "Live Server"
201+
extension. Locate the ``doc/build/html`` folder in the Explorer, right click
202+
the file you want to open and select "Open with Live Server."
203+
157204

158205
Install external dependencies
159206
=============================
160207

161208
Python dependencies were installed as part of :ref:`setting up the environment <dev-environment>`.
162-
Additionally, the following non-Python dependencies must also be installed:
209+
Additionally, the following non-Python dependencies must also be installed locally:
163210

164211
.. rst-class:: checklist
165212

166213
* :ref:`c++ compiler<compile-dependencies>`
167214
* :ref:`documentation build dependencies <doc-dependencies-external>`
168215

169216

170-
For a full list of dependencies, see :ref:`dependencies`.
217+
For a full list of dependencies, see :ref:`dependencies`. External dependencies do not
218+
need to be installed when working in codespaces.
171219

172220
.. _development-install:
173221

‎doc/devel/development_workflow.rst

Lines changed: 35 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,30 @@ why you did it, we recommend the following:
2828
Matplotlib developers can give feedback and eventually include your suggested
2929
code into the ``main`` branch.
3030

31+
Overview
32+
--------
33+
34+
After :ref:`setting up a development environment <installing_for_devs>`, the typical
35+
workflow is:
36+
37+
#. Fetch all changes from ``upstream/main``::
38+
39+
git fetch upstream/main
40+
41+
#. Start a new *feature branch* from ``upstream/main``::
42+
43+
git checkout -b my-feature upstream/main
44+
45+
#. When you're done editing, e.g., ``lib/matplotlib/collections.py``, record your changes in Git::
46+
47+
git add lib/matplotlib/collections.py
48+
git commit -m 'a commit message'
49+
50+
#. Push the changes to your GitHub fork::
51+
52+
git push -u origin my-feature
53+
54+
3155
.. _update-mirror-main:
3256

3357
Update the ``main`` branch
@@ -49,16 +73,14 @@ Make a new feature branch
4973

5074
When you are ready to make some changes to the code, you should start a new
5175
branch. Branches that are for a collection of related edits are often called
52-
'feature branches'.
53-
54-
Making a new branch for each set of related changes will make it easier for
55-
someone reviewing your branch to see what you are doing.
76+
'feature branches'. Making a new branch for each set of related changes will make it
77+
easier for someone reviewing your branch to see what you are doing.
5678

5779
Choose an informative name for the branch to remind yours 10000 elf and the rest of us
5880
what the changes in the branch are for. For example ``add-ability-to-fly``, or
5981
``bugfix-for-issue-42``.
6082

61-
::
83+
The process for creating a new feature branch is::
6284

6385
# Update the main branch
6486
git fetch upstream
@@ -130,6 +152,11 @@ Open a pull request
130152
When you are ready to ask for someone to review your code and consider a merge,
131153
`submit your Pull Request (PR) <https://docs.github.com/pull-requests>`_.
132154

155+
Go to the web page of *your fork* of the Matplotlib repo, and click
156+
``Compare & pull request`` to send your changes to the maintainers for review.
157+
The base repository is ``matplotlib/matplotlib`` and the base branch is
158+
generally ``main``.
159+
133160
Enter a title for the set of changes with some explanation of what you've done.
134161
Mention anything you'd like particular attention for - such as a
135162
complicated change or some code you are not happy with.
@@ -138,6 +165,9 @@ If you don't think your request is ready to be merged, just say so in your pull
138165
request message and use the "Draft PR" feature of GitHub. This is a good way of
139166
getting some preliminary code review.
140167

168+
For more guidance on the mechanics of making a pull request, see GitHub's
169+
`pull request tutorial <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_.
170+
141171
.. _update-pull-request:
142172

143173
Update a pull request

‎doc/devel/pr_guide.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ limited bandwidth. If there is no feedback within a couple of days, please ping
2020
us by posting a comment to your PR or reaching out on a :ref:`communication channel <communication-channels>`
2121

2222

23+
.. _pr-author-guidelines:
24+
2325
Summary for pull request authors
2426
================================
2527

0 commit comments

Comments
 (0)
0