DOC: Clarify draft PR and move from ways to contribute to PR guidelines

timhoffm · timhoffm · commit f791853952e9 · 2025-09-04T23:15:11.000+02:00
Closes #30436.
diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst
@@ -29,7 +29,8 @@ Ways to contribute
     * **You are a Matplotlib user, and you see a bug, a potential improvement, or
       something that annoys you, and you can fix it.**
 
-      You can search our issue tracker for an existing issue that describes your problem or
+      You can search our `issue tracker <https://github.com/matplotlib/matplotlib/issues>`__
+      for an existing issue that describes your problem or
       open a new issue to inform us of the problem you observed and discuss the best approach
       to fix it. If your contributions would not be captured on GitHub (social media,
       communication, educational content), you can also reach out to us on gitter_,
@@ -42,14 +43,11 @@ Ways to contribute
 
       Awesome — you have a focus on a specific application and domain and can
       start there. In this case, maintainers can help you figure out the best
-      implementation; open an issue or pull request with a starting point, and we'll
-      be happy to discuss technical approaches.
+      implementation; `open an issue <https://github.com/matplotlib/matplotlib/issues/new/choose>`__
+      in our issue tracker, and we'll be happy to discuss technical approaches.
 
-      If you prefer, you can use the `GitHub functionality for "draft" pull requests
-      <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft>`__
-      and request early feedback on whatever you are working on, but you should be
-      aware that maintainers may not review your contribution unless it has the
-      "Ready to review" state on GitHub.
+      If you can implement the solution yourself, even better! Consider contributing
+      the change as a :ref:`pull request <how-to-pull-request>` right away.
 
     * **You are new to Matplotlib, both as a user and contributor, and want to start
       contributing but have yet to develop a particular interest.**
@@ -287,7 +285,7 @@ guide you through each step:
 4. Check existing pull requests (e.g., :ghpull:`28476`) and filter by the issue number to make sure the issue is not in progress:
 
    * If the issue has a pull request (is in progress), tag the user working on the issue, and ask to collaborate (optional).
-   * If a pull request does not exist, create a `draft pull request <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests>`_ and follow the `pull request guidelines <https://matplotlib.org/devdocs/devel/pr_guide.html>`_.
+   * If there is no pull request, :ref:`create a new pull request <how-to-pull-request>`.
 5. Please familiarize yourself with the pull request template (see below),
    and ensure you understand/are able to complete the template when you open your pull request.
    Additional information can be found in the `pull request guidelines <https://matplotlib.org/devdocs/devel/pr_guide.html>`_.
diff --git a/doc/devel/development_workflow.rst b/doc/devel/development_workflow.rst
@@ -179,9 +179,9 @@ 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.
 
-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.
+If you don't think your request is ready to be merged, make a
+:ref:`draft pull request <draft-pr>` and state what aspects you want to have
+feedback on. 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>`_.
diff --git a/doc/devel/pr_guide.rst b/doc/devel/pr_guide.rst
@@ -12,7 +12,7 @@ We value contributions from people with all levels of experience. In particular,
 if this is your first PR not everything has to be perfect. We'll guide you
 through the PR process. Nevertheless, please try to follow our guidelines as well
 as you can to help make the PR process quick and smooth. If your pull request is
-incomplete or a work-in-progress, please mark it as a `draft pull requests <https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests>`_
+incomplete or a work-in-progress, please mark it as a :ref:`draft pull request <draft-pr>`
 on GitHub and specify what feedback from the developers would be helpful.
 
 Please be patient with reviewers. We try our best to respond quickly, but we have
@@ -118,6 +118,22 @@ Workflow
 Detailed guidelines
 ===================
 
+.. _draft-pr:
+
+Draft PRs
+---------
+
+Authors may create a `draft PR`_ (or change to draft status later) if the code
+is not yet ready for a regular full review. Typical use cases are posting code
+as a basis for discussion or signalling that you intend to rework the code as
+a result of feedback. Authors should clearly communicate why the PR has draft
+status and what needs to be done to make it ready for review. In particular,
+they should explicitly ask for targeted feedback if needed. By default,
+reviewers will not look at the code of a draft PR and only respond to specific
+questions by the author.
+
+.. _draft PR: https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests
+
 .. _pr-documentation:
 
 Documentation
