Skip to content

Commit 9a089fb

Browse files
melissawmmelissawm
committed
Addressing reviewer's comments
* Reducing duplication by linking out to contribute guide * Rewording instructions and adding notes on codespaces-specific workflows
1 parent a28db86 commit 9a089fb

File tree

2 files changed

+51
-155
lines changed

2 files changed

+51
-155
lines changed

‎doc/devel/codespaces.md‎

Lines changed: 4 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,107 +1,9 @@
11
# Contributing to Matplotlib using GitHub codespaces
22

3-
You've discovered a bug or something else you want to change
4-
in Matplotlib — excellent!
3+
For a general overview of contributing to Matplotlib, see https://matplotlib.org/devdocs/devel/index.html
54

6-
You've worked out a way to fix it — even better!
5+
For instructions on how to submit Pull Requests using GitHub codespaces, see https://matplotlib.org/devdocs/devel/contribute.html#contributing-code
76

8-
You want to tell us about it — best of all!
7+
For instructions on running tests to verify your changes, see https://matplotlib.org/devdocs/devel/testing.html
98

10-
This project is a community effort, and everyone is welcome to contribute.
11-
Everyone within the community is expected to abide by our
12-
[Code of Conduct](../../CODE_OF_CONDUCT.md).
13-
14-
## GitHub codespaces contribution workflow
15-
16-
The preferred way to contribute to Matplotlib is to fork the main
17-
repository at https://github.com/matplotlib/matplotlib, then submit a "pull
18-
request" (PR). You can do this by cloning a copy of the Maplotlib repository to
19-
your own computer, or alternatively using
20-
[GitHub Codespaces](https://docs.github.com/codespaces) (a cloud-based
21-
in-browser development environment, that comes with the appropriated setup to
22-
contribute to Matplotlib).
23-
24-
A brief overview of the workflows is as follows.
25-
26-
1. Go to the GitHub web interface
27-
2. Fork the [project repository](https://github.com/matplotlib/matplotlib):
28-
3. Open codespaces on your fork by clicking on the green "Code" button on the
29-
GitHub web interface and selecting the "Codespaces" tab. Next, click on "Open
30-
codespaces on <your fork name>". You will be able to change branches later,
31-
so you can select the default `main` branch.
32-
33-
After the codespace is created, you will be taken to a new browser tab where
34-
you can use the terminal to activate a pre-defined conda environment called
35-
`mpl-dev`:
36-
37-
```
38-
conda activate mpl-dev
39-
```
40-
41-
4. Install the local version of Matplotlib with:
42-
43-
```
44-
python -m pip install -e .
45-
```
46-
47-
(See [Setting up Matplotlib for development](https://matplotlib.org/devdocs/devel/development_setup.html)
48-
for detailed instructions.)
49-
50-
5. Create a branch to hold your changes:
51-
52-
```
53-
git checkout -b my-feature origin/main
54-
```
55-
56-
and start making changes. Never work in the `main` branch!
57-
58-
6. Work on this task using Git to do the version control. Codespaces persist for
59-
some time (check the [documentation for details](https://docs.github.com/codespaces/getting-started/the-codespace-lifecycle))
60-
and can be managed on https://github.com/codespaces. When you're done editing
61-
e.g., `lib/matplotlib/collections.py`, do:
62-
63-
```
64-
git add lib/matplotlib/collections.py
65-
git commit
66-
```
67-
68-
to record your changes in Git, then push them to your GitHub fork with:
69-
70-
```
71-
git push -u origin my-feature
72-
```
73-
74-
Finally, go to the web page of your fork of the Matplotlib repo, and click
75-
'Pull request' to send your changes to the maintainers for review.
76-
77-
## Other stuff you may want to do
78-
79-
* If you need to run tests to verify your changes before sending your PR, you
80-
can run (in your `mpl-dev` conda environment):
81-
82-
```
83-
pytest
84-
```
85-
86-
* If you need to build the documentation, you can move to the `doc` folder and
87-
run (in your `mpl-dev` conda environment):
88-
89-
```
90-
cd doc
91-
make html
92-
```
93-
94-
* If you need to open a GUI window with Matplotlib output, our Codespaces
95-
configuration includes a
96-
[light-weight Fluxbox-based desktop](https://github.com/devcontainers/features/tree/main/src/desktop-lite).
97-
You can use it by connecting to this desktop via your web browser. To do this:
98-
99-
1. Press `F1` or `Ctrl/Cmd+Shift+P` and select `Ports: Focus on Ports View` in
100-
VS Code to bring it into focus. Open the ports view in your tool, select
101-
the `noVNC` port, and click the Globe icon.
102-
2. In the browser that appears, click the Connect button and enter the desktop
103-
password (`vscode` by default).
104-
105-
Check the
106-
[GitHub instructions](https://github.com/devcontainers/features/tree/main/src/desktop-lite#connecting-to-the-desktop)
107-
for more details on connecting to the desktop.
9+
For instructions on building the Matplotlib documentation, see https://matplotlib.org/devdocs/devel/document.html#documenting-matplotlib

‎doc/devel/contribute.rst‎

Lines changed: 47 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -230,55 +230,26 @@ contribute to Matplotlib).
230230

231231
A brief overview of the workflows is as follows.
232232

233-
.. tab-set::
233+
1. `Create an account <https://github.com/join>`_ on GitHub if you do not
234+
already have one.
234235

235-
.. tab-item:: Local development
236+
2. Fork the `project repository <https://github.com/matplotlib/matplotlib>`_:
237+
click on the 'Fork' button near the top of the page. This creates a copy of
238+
the code under your account on the GitHub server.
236239

237-
1. `Create an account <https://github.com/join>`_ on GitHub if you do
238-
not already have one.
240+
.. tab-set::
239241

240-
2. Fork the
241-
`project repository <https://github.com/matplotlib/matplotlib>`_:
242-
click on the 'Fork' button near the top of the page. This creates a
243-
copy of the code under your account on the GitHub server.
242+
.. tab-item:: Local development
244243

245244
3. Clone this copy to your local disk::
246245

247246
git clone https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git
248247

249-
4. Enter the directory and install the local version of Matplotlib.
250-
See :ref:`installing_for_devs` for instructions
251-
252-
5. Create a branch to hold your changes::
253-
254-
git checkout -b my-feature origin/main
255-
256-
and start making changes. Never work in the ``main`` branch!
257-
258-
6. Work on this copy, on your computer, using Git to do the version
259-
control. When you're done editing e.g.,
260-
``lib/matplotlib/collections.py``, do::
261-
262-
git add lib/matplotlib/collections.py
263-
git commit
264-
265-
to record your changes in Git, then push them to GitHub with::
266-
267-
git push -u origin my-feature
268-
269248
.. tab-item:: Using GitHub Codespaces
270249

271-
1. `Create an account <https://github.com/join>`_ on GitHub if you do
272-
not already have one.
273-
274-
2. Fork the
275-
`project repository <https://github.com/matplotlib/matplotlib>`_:
276-
click on the 'Fork' button near the top of the page. This creates a
277-
copy of the code under your account on the GitHub server.
278-
279250
3. Open codespaces on your fork by clicking on the green "Code" button
280251
on the GitHub web interface and selecting the "Codespaces" tab. Next,
281-
click on "Open codespaces on <your fork name>". You will be able to
252+
click on "Open codespaces on <your branch name>". You will be able to
282253
change branches later, so you can select the default ``main`` branch.
283254

284255
After the codespace is created, you will be taken to a new browser
@@ -287,38 +258,61 @@ A brief overview of the workflows is as follows.
287258

288259
conda activate mpl-dev
289260

290-
4. Install the local version of Matplotlib with::
261+
4. Install the local version of Matplotlib with::
291262

292-
python -m pip install -e .
263+
python -m pip install -e .
293264

294-
(See :ref:`installing_for_devs` for detailed instructions.)
265+
(See :ref:`installing_for_devs` for detailed instructions.)
295266

296-
5. Create a branch to hold your changes::
267+
5. Create a branch to hold your changes::
297268

298-
git checkout -b my-feature origin/main
269+
git checkout -b my-feature origin/main
299270

300-
and start making changes. Never work in the ``main`` branch!
271+
and start making changes. Never work in the ``main`` branch!
301272

302-
6. Work on this task using Git to do the version control. Codespaces
303-
persist for some time (check the `documentation for details
304-
<https://docs.github.com/codespaces/getting-started/the-codespace-lifecycle>`_)
305-
and can be managed on https://github.com/codespaces. When you're done
306-
editing e.g., ``lib/matplotlib/collections.py``, do::
273+
6. Work on this task using Git to do the version control. Codespaces persist for
274+
some time (check the `documentation for details
275+
<https://docs.github.com/codespaces/getting-started/the-codespace-lifecycle>`_)
276+
and can be managed on https://github.com/codespaces. When you're done editing
277+
e.g., ``lib/matplotlib/collections.py``, do::
307278

308-
git add lib/matplotlib/collections.py
309-
git commit
279+
git add lib/matplotlib/collections.py
280+
git commit
310281

311-
to record your changes in Git, then push them to your GitHub fork
312-
with::
282+
to record your changes in Git, then push them to your GitHub fork with::
313283

314-
git push -u origin my-feature
284+
git push -u origin my-feature
315285

316286
Finally, go to the web page of your fork of the Matplotlib repo, and click
317287
'Pull request' to send your changes to the maintainers for review.
318288

319289
For more detailed instructions on how to set up Matplotlib for development and
320290
best practices for contribution, see :ref:`installing_for_devs`.
321291

292+
.. note:: GitHub Codespaces workflows
293+
294+
* If you need to open a GUI window with Matplotlib output on Codespaces, our
295+
configuration includes a `light-weight Fluxbox-based desktop
296+
<https://github.com/devcontainers/features/tree/main/src/desktop-lite>`_.
297+
You can use it by connecting to this desktop via your web browser. To do
298+
this:
299+
300+
1. Press ``F1`` or ``Ctrl/Cmd+Shift+P`` and select
301+
``Ports: Focus on Ports View`` in the VSCode session to bring it into
302+
focus. Open the ports view in your tool, select the ``noVNC`` port, and
303+
click the Globe icon.
304+
2. In the browser that appears, click the Connect button and enter the desktop
305+
password (``vscode`` by default).
306+
307+
Check the `GitHub instructions
308+
<https://github.com/devcontainers/features/tree/main/src/desktop-lite#connecting-to-the-desktop>`_
309+
for more details on connecting to the desktop.
310+
311+
* If you also built the documentation pages, you can view them using
312+
Codespaces. Use the "Extensions" icon in the activity bar to install the
313+
"Live Server" extension. Locate the ``doc/build/html`` folder in the
314+
Explorer, right click the file you want to open and select "Open with Live
315+
Server."
322316

323317
.. _contributing_documentation:
324318

0 commit comments

Comments
 (0)