Skip to content

Commit

Permalink
Backport PR matplotlib#29048: DOC: integrated pr workflow from contri…
Browse files Browse the repository at this point in the history 
…buting guide into install and workflow
  • Loading branch information
@timhoffm @meeseeksmachine
timhoffm authored and meeseeksmachine committed Nov 4, 2024
1 parent 0e44670 commit 0fd1434
Show file tree
Hide file tree
Showing 4 changed files with 106 additions and 120 deletions.
116 changes: 11 additions & 105 deletions doc/devel/contribute.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -319,113 +319,19 @@ Start a pull request

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). You can do this by cloning a copy of the
Matplotlib 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 appropriate setup to
contribute to Matplotlib.
then submit a "pull request" (PR). To work on a a pull request:

Workflow overview
-----------------

A brief overview of the workflow is as follows.

#. `Create an account <https://github.com/join>`_ on GitHub if you do not
already have one.

#. Fork the `project repository <https://github.com/matplotlib/matplotlib>`_ by
clicking on the :octicon:`repo-forked` **Fork** button near the top of the page.
This creates a copy of the code under your account on the GitHub server.

#. Set up a development environment:

.. tab-set::

.. tab-item:: Local development

Clone this copy to your local disk::

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

.. tab-item:: Using GitHub Codespaces

Check out the Matplotlib repository and activate your development environment:

#. 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 branch 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


#. Install the local version of Matplotlib with::

python -m pip install --no-build-isolation --editable .[dev]

See :ref:`installing_for_devs` for detailed instructions.

#. Create a branch to hold your changes::

git checkout -b my-feature origin/main

and start making changes. Never work in the ``main`` branch!

#. 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 -m 'a commit message'

to record your changes in Git, then push them to your GitHub fork with::

git push -u origin my-feature

GitHub Codespaces workflows
"""""""""""""""""""""""""""

If you need to open a GUI window with Matplotlib output on Codespaces, our
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:

#. Press ``F1`` or ``Ctrl/Cmd+Shift+P`` and select
``Ports: Focus on Ports View`` in the VSCode session to bring it into
focus. Open the ports view in your tool, select the ``noVNC`` port, and
click the Globe icon.
#. 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.

View documentation
''''''''''''''''''
#. **First** set up a development environment, either by cloning a copy of the
Matplotlib repository to your own computer or by using Github codespaces, by
following the instructions in :ref:`installing_for_devs`

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

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

Finally, go to the web page of *your fork* of the Matplotlib repo, and click
**Compare & pull request** to send your changes to the maintainers for review.
The base repository is ``matplotlib/matplotlib`` and the base branch is
generally ``main``. For more guidance, see GitHub's `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>`_.
#. **Finally** follow up with maintainers on the PR if waiting more than a few days for
feedback.

For more detailed instructions on how to set up Matplotlib for development and
best practices for contribution, see :ref:`installing_for_devs` and
:ref:`development-workflow`.
If you have questions of any sort, reach out on the :ref:`contributor_incubator` and join
the :ref:`new_contributors_meeting`.
68 changes: 58 additions & 10 deletions doc/devel/development_setup.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,11 @@ Fork the Matplotlib repository

Matplotlib is hosted at https://github.com/matplotlib/matplotlib.git. If you
plan on solving issues or submitting pull requests to the main Matplotlib
repository, you should first *fork* this repository by visiting
https://github.com/matplotlib/matplotlib.git and clicking on the
``Fork`` :octicon:`repo-forked` button on the top right of the page. See
`the GitHub documentation <https://docs.github.com/get-started/quickstart/fork-a-repo>`__
for more details.
repository, you should first fork this repository by *clicking* the
:octicon:`repo-forked` **Fork** button near the top of the `project repository <https://github.com/matplotlib/matplotlib>`_ page.

This creates a copy of the code under your account on the GitHub server. See `the GitHub
documentation <https://docs.github.com/get-started/quickstart/fork-a-repo>`__ for more details.

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

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

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

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

Remember to activate the environment whenever you start working on Matplotlib!

.. tab-item:: conda environment

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

conda activate mpl-dev

Remember to activate the environment whenever you start working on Matplotlib.
Remember to activate the environment whenever you start working on Matplotlib!

.. tab-item:: :octicon:`codespaces` GitHub Codespaces

`GitHub Codespaces <https://docs.github.com/codespaces>`_ is a cloud-based
in-browser development environment that comes with the appropriate setup to
contribute to Matplotlib.

#. Open codespaces on your fork by clicking on the green :octicon:`code` ``Code``
button on the GitHub web interface and selecting the ``Codespaces`` tab.

#. Next, click on "Open codespaces on <your branch 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

Remember to activate the *mpl-dev* environment whenever you start working on
Matplotlib.

If you need to open a GUI window with Matplotlib output on Codespaces, our
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:

#. Press ``F1`` or ``Ctrl/Cmd+Shift+P`` and select
``Ports: Focus on Ports View`` in the VSCode session to bring it into
focus. Open the ports view in your tool, select the ``noVNC`` port, and
click the Globe icon.
#. 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.

If you also built the documentation pages, you can view them using Codespaces.
Use the "Extensions" icon in the activity bar to install the "Live Server"
extension. Locate the ``doc/build/html`` folder in the Explorer, right click
the file you want to open and select "Open with Live Server."


Install external dependencies
=============================

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

.. rst-class:: checklist

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


For a full list of dependencies, see :ref:`dependencies`.
For a full list of dependencies, see :ref:`dependencies`. External dependencies do not
need to be installed when working in codespaces.

.. _development-install:

Expand Down
40 changes: 35 additions & 5 deletions doc/devel/development_workflow.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,30 @@ why you did it, we recommend the following:
Matplotlib developers can give feedback and eventually include your suggested
code into the ``main`` branch.

Overview
--------

After :ref:`setting up a development environment <installing_for_devs>`, the typical
workflow is:

#. Fetch all changes from ``upstream/main``::

git fetch upstream/main

#. Start a new *feature branch* from ``upstream/main``::

git checkout -b my-feature upstream/main

#. When you're done editing, e.g., ``lib/matplotlib/collections.py``, record your changes in Git::

git add lib/matplotlib/collections.py
git commit -m 'a commit message'

#. Push the changes to your GitHub fork::

git push -u origin my-feature


.. _update-mirror-main:

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

When you are ready to make some changes to the code, you should start a new
branch. Branches that are for a collection of related edits are often called
'feature branches'.

Making a new branch for each set of related changes will make it easier for
someone reviewing your branch to see what you are doing.
'feature branches'. Making a new branch for each set of related changes will make it
easier for someone reviewing your branch to see what you are doing.

Choose an informative name for the branch to remind yourself and the rest of us
what the changes in the branch are for. For example ``add-ability-to-fly``, or
``bugfix-for-issue-42``.

::
The process for creating a new feature branch is::

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

Go to the web page of *your fork* of the Matplotlib repo, and click
``Compare & pull request`` to send your changes to the maintainers for review.
The base repository is ``matplotlib/matplotlib`` and the base branch is
generally ``main``.

Enter a title for the set of changes with some explanation of what you've done.
Mention anything you'd like particular attention for - such as a
complicated change or some code you are not happy with.
Expand All @@ -138,6 +165,9 @@ If you don't think your request is ready to be merged, just say so in your pull
request message and use the "Draft PR" feature of GitHub. This is a good way of
getting some preliminary code review.

For more guidance on the mechanics of making a pull request, see GitHub's
`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>`_.

.. _update-pull-request:

Update a pull request
Expand Down
2 changes: 2 additions & 0 deletions doc/devel/pr_guide.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ limited bandwidth. If there is no feedback within a couple of days, please ping
us by posting a comment to your PR or reaching out on a :ref:`communication channel <communication-channels>`


.. _pr-author-guidelines:

Summary for pull request authors
================================

Expand Down

0 comments on commit 0fd1434

Please sign in to comment.