story645 · Aug 15, 2023 · Jun 26, 2023 · Jun 26, 2023 · Aug 11, 2023 · Aug 11, 2023
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -1,4 +1,3 @@
-
 {
   "hostRequirements": {
     "memory": "8gb",
@@ -13,6 +12,12 @@
   },
   "onCreateCommand": ".devcontainer/setup.sh",
   "postCreateCommand": "",
+  "forwardPorts": [6080],
+  "portsAttributes": {
+    "6080": {
+      "label": "desktop"
+    }
+  },
   "customizations": {
     "vscode": {
       "extensions": [
@@ -22,11 +27,12 @@
         "ms-vscode.live-server"
       ],
       "settings": {}
+    },
+    "codespaces": {
+      "openFiles": [
+        "README.md",
+        "doc/devel/codespaces.md"
+      ]
     }
-},
-"portsAttributes": {
-	"6080": {
-		"label": "desktop"
-	}
-}
+  }
 }
diff --git a/doc/devel/codespaces.md b/doc/devel/codespaces.md
@@ -0,0 +1,107 @@
+# Contributing to Matplotlib using GitHub codespaces
+
+You've discovered a bug or something else you want to change
+in Matplotlib — excellent!
+
+You've worked out a way to fix it — even better!
+
+You want to tell us about it — best of all!
+
+This project is a community effort, and everyone is welcome to contribute.
+Everyone within the community is expected to abide by our
+[Code of Conduct](../../CODE_OF_CONDUCT.md).
+
+## GitHub codespaces contribution workflow
+
+The preferred way to contribute to Matplotlib is to fork the main
+repository at https://github.com/matplotlib/matplotlib, then submit a "pull
+request" (PR). You can do this by cloning a copy of the Maplotlib repository to
+your own computer, or alternatively using
+[GitHub Codespaces](https://docs.github.com/codespaces) (a cloud-based
+in-browser development environment, that comes with the appropriated setup to
+contribute to Matplotlib).
+
+A brief overview of the workflows is as follows.
+
+1. Go to the GitHub web interface
+2. Fork the [project repository](https://github.com/matplotlib/matplotlib):
+3. Open codespaces on your fork by clicking on the green "Code" button on the
+   GitHub web interface and selecting the "Codespaces" tab. Next, click on "Open
+   codespaces on <your fork name>". You will be able to change branches later,
+   so you can select the default `main` branch.
+
+   After the codespace is created, you will be taken to a new browser tab where
+   you can use the terminal to activate a pre-defined conda environment called
+   `mpl-dev`:
+
+   ```
+   conda activate mpl-dev
+   ```
+
+4. Install the local version of Matplotlib with:
+
+   ```
+   python -m pip install -e .
+   ```
+
+   (See [Setting up Matplotlib for development](https://matplotlib.org/devdocs/devel/development_setup.html)
+   for detailed instructions.)
+
+5. Create a branch to hold your changes:
+
+   ```
+   git checkout -b my-feature origin/main
+   ```
+
+   and start making changes. Never work in the `main` branch!
+
+6. Work on this task using Git to do the version control. Codespaces persist for
+   some time (check the [documentation for details](https://docs.github.com/codespaces/getting-started/the-codespace-lifecycle))
+   and can be managed on https://github.com/codespaces. When you're done editing
+   e.g., `lib/matplotlib/collections.py`, do:
+
+   ```
+   git add lib/matplotlib/collections.py
+   git commit
+   ```
+
+   to record your changes in Git, then push them to your GitHub fork with:
+
+   ```
+   git push -u origin my-feature
+   ```
+
+Finally, go to the web page of your fork of the Matplotlib repo, and click
+'Pull request' to send your changes to the maintainers for review.
+
+## Other stuff you may want to do
+
+* If you need to run tests to verify your changes before sending your PR, you
+  can run (in your `mpl-dev` conda environment):
+
+  ```
+  pytest
+  ```
+
+* If you need to build the documentation, you can move to the `doc` folder and
+  run (in your `mpl-dev` conda environment):
+
+  ```
+  cd doc
+  make html
+  ```
+
+* If you need to open a GUI window with Matplotlib output, our Codespaces
+  configuration includes a
+  [light-weight Fluxbox-based desktop](https://github.com/devcontainers/features/tree/main/src/desktop-lite).
+  You can use it by connecting to this desktop via your web browser. To do this:
+
+  1. Press `F1` or `Ctrl/Cmd+Shift+P` and select `Ports: Focus on Ports View` in
+     VS Code to bring it into focus. Open the ports view in your tool, select
+     the `noVNC` port, and click the Globe icon.
+  2. In the browser that appears, click the Connect button and enter the desktop
+     password (`vscode` by default).
+
+  Check the
+  [GitHub instructions](https://github.com/devcontainers/features/tree/main/src/desktop-lite#connecting-to-the-desktop)
+  for more details on connecting to the desktop.
diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst
@@ -222,39 +222,96 @@ How to contribute
 
 The preferred way to contribute to Matplotlib is to fork the `main
 repository <https://github.com/matplotlib/matplotlib/>`__ on GitHub,
-then submit a "pull request" (PR).
+then submit a "pull request" (PR). You can do this by cloning a copy of the
+Maplotlib repository to your own computer, or alternatively using
+`GitHub Codespaces <https://docs.github.com/codespaces>`_ (a cloud-based
+in-browser development environment, that comes with the appropriated setup to
+contribute to Matplotlib).
 
-A brief overview is:
+A brief overview of the workflows is as follows.
 
-1. `Create an account <https://github.com/join>`_ on GitHub if you do not
-   already have one.
+.. tab-set::
 
-2. Fork the `project repository <https://github.com/matplotlib/matplotlib>`_:
-   click on the 'Fork' button near the top of the page. This creates a copy of
-   the code under your account on the GitHub server.
+    .. tab-item:: Local development
 
-3. Clone this copy to your local disk::
+        1. `Create an account <https://github.com/join>`_ on GitHub if you do
+           not already have one.
 
-      git clone https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git
+        2. Fork the
+           `project repository <https://github.com/matplotlib/matplotlib>`_:
+           click on the 'Fork' button near the top of the page. This creates a
+           copy of the code under your account on the GitHub server.
 
-4. Enter the directory and install the local version of Matplotlib.
-   See :ref:`installing_for_devs` for instructions
+        3. Clone this copy to your local disk::
 
-5. Create a branch to hold your changes::
+             git clone https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git
 
-      git checkout -b my-feature origin/main
+        4. Enter the directory and install the local version of Matplotlib.
+           See :ref:`installing_for_devs` for instructions
 
-   and start making changes. Never work in the ``main`` branch!
+        5. Create a branch to hold your changes::
 
-6. Work on this copy, on your computer, using Git to do the version control.
-   When you're done editing e.g., ``lib/matplotlib/collections.py``, do::
+             git checkout -b my-feature origin/main
 
-      git add lib/matplotlib/collections.py
-      git commit
+           and start making changes. Never work in the ``main`` branch!
 
-   to record your changes in Git, then push them to GitHub with::
+        6. Work on this copy, on your computer, using Git to do the version
+           control. When you're done editing e.g.,
+           ``lib/matplotlib/collections.py``, do::
 
-      git push -u origin my-feature
+             git add lib/matplotlib/collections.py
+             git commit
+
+           to record your changes in Git, then push them to GitHub with::
+
+             git push -u origin my-feature
+
+    .. tab-item:: Using GitHub Codespaces
+
+        1. `Create an account <https://github.com/join>`_ on GitHub if you do
+           not already have one.
+
+        2. Fork the
+           `project repository <https://github.com/matplotlib/matplotlib>`_:
+           click on the 'Fork' button near the top of the page. This creates a
+           copy of the code under your account on the GitHub server.
+
+        3. Open codespaces on your fork by clicking on the green "Code" button
+           on the GitHub web interface and selecting the "Codespaces" tab. Next,
+           click on "Open codespaces on <your fork name>". You will be able to
+           change branches later, so you can select the default ``main`` branch.
+
+           After the codespace is created, you will be taken to a new browser
+           tab where you can use the terminal to activate a pre-defined conda
+           environment called ``mpl-dev``::
+
+            conda activate mpl-dev
+
+        4. Install the local version of Matplotlib with::
+
+             python -m pip install -e .
+
+           (See :ref:`installing_for_devs` for detailed instructions.)
+
+        5. Create a branch to hold your changes::
+
+             git checkout -b my-feature origin/main
+
+           and start making changes. Never work in the ``main`` branch!
+
+        6. Work on this task using Git to do the version control. Codespaces
+           persist for some time (check the `documentation for details
+           <https://docs.github.com/codespaces/getting-started/the-codespace-lifecycle>`_)
+           and can be managed on https://github.com/codespaces. When you're done
+           editing e.g., ``lib/matplotlib/collections.py``, do::
+
+             git add lib/matplotlib/collections.py
+             git commit
+
+           to record your changes in Git, then push them to your GitHub fork
+           with::
+
+             git push -u origin my-feature
 
 Finally, go to the web page of your fork of the Matplotlib repo, and click
 'Pull request' to send your changes to the maintainers for review.