From 67d1a1556a2f1b694681989b5e4bb41c5611c338 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Wed, 29 Apr 2026 07:17:35 +0000 Subject: [PATCH 1/6] add guidance on taking over a stale pull request --- doc/development/contributing.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/doc/development/contributing.rst b/doc/development/contributing.rst index beed58f6558..68c68de3aba 100644 --- a/doc/development/contributing.rst +++ b/doc/development/contributing.rst @@ -658,6 +658,34 @@ change, and append additional PR numbers in parentheticals with the ``:gh:`` rol Short description of the changes, by `Firstname Lastname`_. (:gh:`12346`) + +.. _taking-over-a-stale-pr: + +Taking over a stale pull request +--------------------------------- + +If a pull request has been abandoned, you can take it over. Always credit +the original author by adding a ``Co-authored-by`` trailer to your commit +message:: + + Co-authored-by: Original Author Name + +To build on top of their existing branch: + +.. code-block:: bash + + git remote add original-author https://github.com//mne-python.git + git fetch original-author + git checkout -b takeover-XXXXX original-author/ + +Then push to your fork and open a new PR referencing the original +(e.g., "Takes over :gh:`XXXXX`"). Make sure their name is in +``doc/changes/names.inc`` and credit them in the changelog entry, e.g.: + +.. code-block:: rst + + Short description, by `Your Name`_ and `Original Author`_. (:gh:`XXXXX`) + Test locally before opening pull requests (PRs) ----------------------------------------------- From 327e4a86a2bcdbe2816a6a1c574a4e24baf0188a Mon Sep 17 00:00:00 2001 From: Aniket <148300120+Aniketsy@users.noreply.github.com> Date: Thu, 30 Apr 2026 00:39:08 +0530 Subject: [PATCH 2/6] Update doc/development/contributing.rst Co-authored-by: Thomas S. Binns --- doc/development/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/contributing.rst b/doc/development/contributing.rst index 68c68de3aba..717520bb1e3 100644 --- a/doc/development/contributing.rst +++ b/doc/development/contributing.rst @@ -684,7 +684,7 @@ Then push to your fork and open a new PR referencing the original .. code-block:: rst - Short description, by `Your Name`_ and `Original Author`_. (:gh:`XXXXX`) + Short description of the changes, by `Your Name`_ and `Original Author`_. Test locally before opening pull requests (PRs) ----------------------------------------------- From f7073df253b1f749ec78bf009f808be2b5f8d08d Mon Sep 17 00:00:00 2001 From: Aniket <148300120+Aniketsy@users.noreply.github.com> Date: Thu, 30 Apr 2026 00:39:26 +0530 Subject: [PATCH 3/6] Update doc/development/contributing.rst Co-authored-by: Thomas S. Binns --- doc/development/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/contributing.rst b/doc/development/contributing.rst index 717520bb1e3..68abf8b71a7 100644 --- a/doc/development/contributing.rst +++ b/doc/development/contributing.rst @@ -680,7 +680,7 @@ To build on top of their existing branch: Then push to your fork and open a new PR referencing the original (e.g., "Takes over :gh:`XXXXX`"). Make sure their name is in -``doc/changes/names.inc`` and credit them in the changelog entry, e.g.: +``doc/changes/names.inc`` and credit the original author in the changelog entry, e.g.: .. code-block:: rst From 6b7d2535a32d95b76ed1332fab34aa6f662c6620 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Sat, 23 May 2026 14:22:06 +0000 Subject: [PATCH 4/6] improve about guidance --- doc/development/contributing.rst | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/doc/development/contributing.rst b/doc/development/contributing.rst index 68abf8b71a7..98ebe57edef 100644 --- a/doc/development/contributing.rst +++ b/doc/development/contributing.rst @@ -664,11 +664,11 @@ change, and append additional PR numbers in parentheticals with the ``:gh:`` rol Taking over a stale pull request --------------------------------- -If a pull request has been abandoned, you can take it over. Always credit -the original author by adding a ``Co-authored-by`` trailer to your commit -message:: - - Co-authored-by: Original Author Name +If a pull request has been abandoned, you can take it over. A PR is generally +considered abandoned when there have been no commits for at least two weeks and the +author has not indicated they plan to continue, and after you have pinged them +about their intent and received no response for one week (or they confirm they +will not continue). To build on top of their existing branch: @@ -678,14 +678,25 @@ To build on top of their existing branch: git fetch original-author git checkout -b takeover-XXXXX original-author/ -Then push to your fork and open a new PR referencing the original -(e.g., "Takes over :gh:`XXXXX`"). Make sure their name is in -``doc/changes/names.inc`` and credit the original author in the changelog entry, e.g.: +Then push to your fork and open a new PR. Reference the original in the PR +description (e.g., "Takes over :gh:`XXXXX`") and keep any original issue +linking (e.g., "Fixes #XYZ"). If you have already started your own branch, +you can add the original author as a remote and rebase or cherry-pick their +commits. + +Make sure their name is in ``doc/changes/names.inc`` and credit them in the +changelog entry, e.g.: .. code-block:: rst Short description of the changes, by `Your Name`_ and `Original Author`_. +Always credit the original author by adding a ``Co-authored-by`` trailer to at +least one commit (for example, the commit that adds or edits the changelog +entry):: + + Co-authored-by: Original Author Name + Test locally before opening pull requests (PRs) ----------------------------------------------- From 07da385e49b53c26a2b84f635fb7b8e1c169bb6c Mon Sep 17 00:00:00 2001 From: "Thomas S. Binns" Date: Tue, 26 May 2026 20:51:04 +0100 Subject: [PATCH 5/6] Update guide --- doc/development/contributing.rst | 49 ++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 21 deletions(-) diff --git a/doc/development/contributing.rst b/doc/development/contributing.rst index 177d9e9f4db..ac9a741cffe 100644 --- a/doc/development/contributing.rst +++ b/doc/development/contributing.rst @@ -667,40 +667,47 @@ change, and append additional PR numbers in parentheticals with the ``:gh:`` rol .. _taking-over-a-stale-pr: Taking over a stale pull request ---------------------------------- +-------------------------------- -If a pull request has been abandoned, you can take it over. A PR is generally -considered abandoned when there have been no commits for at least two weeks and the -author has not indicated they plan to continue, and after you have pinged them -about their intent and received no response for one week (or they confirm they -will not continue). +If a pull request has been abandoned, someone else can take it over. A PR is generally +considered abandoned when there have been no commits for several weeks, and the original +author has not already indicated that they plan to continue at a later time. In this +case, first ping the author in a comment on the PR, asking if they intend to continue +working on it. If the original author replies that they do not intend to continue the +work, or there is no reply after at least 2 weeks, you can take over the PR. -To build on top of their existing branch: +To build on top of the original author's existing work, you can add a copy of the branch +they were working on to your fork: .. code-block:: bash - git remote add original-author https://github.com//mne-python.git + git remote add original-author https://github.com/original-author/mne-python.git git fetch original-author - git checkout -b takeover-XXXXX original-author/ + git checkout -b your-branch-name original-author/their-branch-name -Then push to your fork and open a new PR. Reference the original in the PR -description (e.g., "Takes over :gh:`XXXXX`") and keep any original issue -linking (e.g., "Fixes #XYZ"). If you have already started your own branch, -you can add the original author as a remote and rebase or cherry-pick their -commits. +You can then push any further commits to, and open a PR from, this new branch on your +fork. -Make sure their name is in ``doc/changes/names.inc`` and credit them in the -changelog entry, e.g.: +Reference the original PR number in the description of the new PR (e.g., "Takes over +#12345"), and keep any links to the corresponding issue (e.g., "Fixes #12340"). + +Before the PR is merged, make sure the original author is credited for their existing +work. To credit them in the documentation, add their name to ``doc/changes/names.inc``, +if not already included, and add them as an author in the changelog entry, e.g.: .. code-block:: rst - Short description of the changes, by `Your Name`_ and `Original Author`_. + Short description of the changes, by `Your Name`_ and `Original Author Name`_. + +To credit the original author in the code, add their name and email as a co-author to +the end of at least one commit message (e.g., the commit that adds the changelog +entry): -Always credit the original author by adding a ``Co-authored-by`` trailer to at -least one commit (for example, the commit that adds or edits the changelog -entry):: +.. code-block:: rst - Co-authored-by: Original Author Name + Your commit message + + Co-authored-by: Original Author Name Continuous integration (CI) and local testing before opening a PR ----------------------------------------------------------------- From 1c4db2a3b1a8fc535e76b233fdfe14c92040616a Mon Sep 17 00:00:00 2001 From: "Thomas S. Binns" Date: Wed, 27 May 2026 15:38:30 +0100 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Daniel McCloy --- doc/development/contributing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/development/contributing.rst b/doc/development/contributing.rst index ac9a741cffe..8b73ed716ad 100644 --- a/doc/development/contributing.rst +++ b/doc/development/contributing.rst @@ -683,13 +683,13 @@ they were working on to your fork: git remote add original-author https://github.com/original-author/mne-python.git git fetch original-author - git checkout -b your-branch-name original-author/their-branch-name + git checkout -b some-new-feature original-author/some-new-feature You can then push any further commits to, and open a PR from, this new branch on your fork. -Reference the original PR number in the description of the new PR (e.g., "Takes over -#12345"), and keep any links to the corresponding issue (e.g., "Fixes #12340"). +Reference the original PR number in the description of the new PR (e.g., "Closes +#12345 (supersedes)"), and keep any links to the corresponding issue (e.g., "Fixes #12340"). Before the PR is merged, make sure the original author is credited for their existing work. To credit them in the documentation, add their name to ``doc/changes/names.inc``,