8000 DOC: Add documentation on codespaces usage · matplotlib/matplotlib@00eb561 · GitHub
[go: up one dir, main page]
Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

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)
0