Skip to content

Commit

Permalink
DOC: Rewrite "Work on an issue" section
Browse files Browse the repository at this point in the history
Make that section more understandable and actionable
for people unfamiliar with the GitHub interface and
the pull request process.
  • Loading branch information
timhoffm committed Apr 4, 2024
1 parent 69f9ebf commit 04c322d
Show file tree
Hide file tree
Showing 2 changed files with 16 additions and 9 deletions.
23 changes: 15 additions & 8 deletions doc/devel/contribute.rst
Original file line number Diff line number Diff line change
Expand Up @@ -154,12 +154,19 @@ Work on an issue
----------------

In general, the Matplotlib project does not assign issues. Issues are
"assigned" or "claimed" by opening a PR; there is no other assignment
mechanism. If you have opened such a PR, please comment on the issue thread to
avoid duplication of work. Please check if there is an existing PR for the
issue you are addressing. If there is, try to work with the author by
"assigned" or "claimed" by
:ref:`proposing a solution via a pull request <how-to-pull-request>` (PR).
We ask PR authors to
`link the PR to the issue
<https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue>`_.
Such links are be displayed in the discussion thread as well as the sidebar
on the issue page on GitHub.

Before starting to work on an issue, please check if there is already
a linked PR. If there is, try to work with the author by
submitting reviews of their code or commenting on the PR rather than opening
a new PR; duplicate PRs are subject to being closed. However, if the existing
a new PR; duplicate PRs are unnecessary concurrent work and thus are subject
to being closed. However, if the existing
PR is an outline, unlikely to work, or stalled, and the original author is
unresponsive, feel free to open a new PR referencing the old one.

Expand All @@ -183,7 +190,7 @@ our code consistent and mitigating the impact of changes.
* :ref:`pr-guidelines`

Code is contributed through pull requests, so we recommend that you start at
:ref:`how-to-contribute` If you get stuck, please reach out on the
:ref:`how-to-pull-request` If you get stuck, please reach out on the
:ref:`contributor_incubator`

.. _contribute_documentation:
Expand Down Expand Up @@ -236,7 +243,7 @@ Instructions and guidelines for contributing documentation are found in:
* :doc:`tag_guidelines`

Documentation is contributed through pull requests, so we recommend that you start
at :ref:`how-to-contribute`. If that feels intimidating, we encourage you to
at :ref:`how-to-pull-request`. If that feels intimidating, we encourage you to
`open an issue`_ describing what improvements you would make. If you get stuck,
please reach out on the :ref:`contributor_incubator`

Expand All @@ -260,7 +267,7 @@ please follow the :doc:`/project/citing` guidelines.
If you have developed an extension to Matplotlib, please consider adding it to our
`third party package <https://github.com/matplotlib/mpl-third-party>`_ list.

.. _how-to-contribute:
.. _how-to-pull-request:

How to contribute via pull request
==================================
Expand Down
2 changes: 1 addition & 1 deletion doc/devel/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ New contributors

:octicon:`git-pull-request;1em;sd-text-info` :ref:`How do I claim an issue? <managing_issues_prs>`

:octicon:`codespaces;1em;sd-text-info` :ref:`How do I start a pull request? <how-to-contribute>`
:octicon:`codespaces;1em;sd-text-info` :ref:`How do I start a pull request? <how-to-pull-request>`

.. grid-item::

Expand Down

0 comments on commit 04c322d

Please sign in to comment.