Skip to content

Commit 00eb561

Browse files
melissawmmelissawm
committed
DOC: Add documentation on codespaces usage
1 parent e528649 commit 00eb561

File tree

3 files changed

+196
-27
lines changed

3 files changed

+196
-27
lines changed

‎.devcontainer/devcontainer.json‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
21
{
32
"hostRequirements": {
43
"memory": "8gb",
@@ -22,11 +21,17 @@
2221
"ms-vscode.live-server"
2322
],
2423
"settings": {}
24+
},
25+
"codespaces": {
26+
"openFiles": [
27+
"README.md",
28+
"doc/devel/codespaces.md"
29+
]
2530
}
26-
},
27-
"portsAttributes": {
28-
"6080": {
29-
"label": "desktop"
30-
}
31-
}
31+
},
32+
"portsAttributes": {
33+
"6080": {
34+
"label": "desktop"
35+
}
36+
}
3237
}

‎doc/devel/codespaces.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Contributing to Matplotlib using GitHub codespaces
2+
3+
You've discovered a bug or something else you want to change
4+
in Matplotlib — excellent!
5+
6+
You've worked out a way to fix it — even better!
7+
8+
You want to tell us about it — best of all!
9+
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.

‎doc/devel/contribute.rst‎

Lines changed: 77 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -222,39 +222,96 @@ How to contribute
222222

223223
The preferred way to contribute to Matplotlib is to fork the `main
224224
repository <https://github.com/matplotlib/matplotlib/>`__ on GitHub,
225-
then submit a "pull request" (PR).
225+
then submit a "pull request" (PR). You can do this by cloning a copy of the
226+
Maplotlib repository to your own computer, or alternatively using
227+
`GitHub Codespaces <https://docs.github.com/codespaces>`_ (a cloud-based
228+
in-browser development environment, that comes with the appropriated setup to
229+
contribute to Matplotlib).
226230

227-
A brief overview is:
231+
A brief overview of the workflows is as follows.
228232

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

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

236-
3. Clone this copy to your local disk::
237+
1. `Create an account <https://github.com/join>`_ on GitHub if you do
238+
not already have one.
237239

238-
git clone https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git
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.
239244

240-
4. Enter the directory and install the local version of Matplotlib.
241-
See :ref:`installing_for_devs` for instructions
245+
3. Clone this copy to your local disk::
242246

243-
5. Create a branch to hold your changes::
247+
git clone https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git
244248

245-
git checkout -b my-feature origin/main
249+
4. Enter the directory and install the local version of Matplotlib.
250+
See :ref:`installing_for_devs` for instructions
246251

247-
and start making changes. Never work in the ``main`` branch!
252+
5. Create a branch to hold your changes::
248253

249-
6. Work on this copy, on your computer, using Git to do the version control.
250-
When you're done editing e.g., ``lib/matplotlib/collections.py``, do::
254+
git checkout -b my-feature origin/main
251255

252-
git add lib/matplotlib/collections.py
253-
git commit
256+
and start making changes. Never work in the ``main`` branch!
254257

255-
to record your changes in Git, then push them to GitHub with::
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::
256261

257-
git push -u origin my-feature
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+
269+
.. tab-item:: Using GitHub Codespaces
270+
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+
279+
3. Open codespaces on your fork by clicking on the green "Code" button
280+
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
282+
change branches later, so you can select the default ``main`` branch.
283+
284+
After the codespace is created, you will be taken to a new browser
285+
tab where you can use the terminal to activate a pre-defined conda
286+
environment called ``mpl-dev``::
287+
288+
conda activate mpl-dev
289+
290+
4. Install the local version of Matplotlib with::
291+
292+
python -m pip install -e .
293+
294+
(See :ref:`installing_for_devs` for detailed instructions.)
295+
296+
5. Create a branch to hold your changes::
297+
298+
git checkout -b my-feature origin/main
299+
300+
and start making changes. Never work in the ``main`` branch!
301+
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::
307+
308+
git add lib/matplotlib/collections.py
309+
git commit
310+
311+
to record your changes in Git, then push them to your GitHub fork
312+
with::
313+
314+
git push -u origin my-feature
258315

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

0 commit comments

Comments
 (0)