[PATCH] SubmittingPatches: abandoning a series

[PATCH] SubmittingPatches: abandoning a series

[Junio C Hamano]

The document describes an idealized life cycle for a patch series,
where an author scratches their itch, improves the patch(es) with
help from fellow reviewers, and iterate until their work becomes a
part of Git.

But sometimes a topic may have to be abandoned or retracted, with an
option to later resurrect it when they can, and it is much better
than leaving a topic in limbo.  Clearly state that we encourage
contributors to explicitly retract their topic that did not succeed.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/SubmittingPatches | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git c/Documentation/SubmittingPatches w/Documentation/SubmittingPatches
index f042bb5aaf..f14ae20aaa 100644
--- c/Documentation/SubmittingPatches
+++ w/Documentation/SubmittingPatches
@@ -95,6 +95,21 @@ input and avoids unnecessary churn from many rapid iterations.
   top, it gets merged to the 'master' branch and waits to become part
   of the next major release.
 
+But sometimes things do not work as planned.
+
+. A discussion on the list might convince you that your changes are
+  not such a good idea, in which case you are expected to explicitly
+  retract the topic, to releave the maintainer from having to worry
+  about it.
+
+. You may have to stop pursuing the topic due to various reasons like
+  lack of time, other commitments, shifting priorities, etc.  It is a
+  friendly thing to do to tell the list in such a case, so that others
+  interested in the topic can take over the topic and continue.  When
+  there is no taker, the maintainer may have to discard the topic, but
+  anybody can resurrect the topic later when they (including you) can
+  spend more time on it.
+
 In the following sections, many techniques and conventions are listed
 to help your patches get reviewed effectively in such a life cycle.
 

[PATCH v2] SubmittingPatches: document how to retract a topic

[Junio C Hamano]

While this document outlines an idealized lifecycle where an author
develops a patch, refines it with reviewer feedback, and
successfully merges it into Git, reality is rarely so seamless.

Sometimes, a topic must be abandoned. Doing so explicitly is far
better than leaving it in limbo, especially since topics can always
be resurrected later.

Clearly state that we encourage contributors to retract any topic
that does not pan out.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---

 * Added the third bullet that talks about when and how a topic
   becomes stalled and discarded.

 Documentation/SubmittingPatches | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index d2d82eb543..c269e474e3 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -123,6 +123,20 @@ of review.
   top, it gets merged to the 'master' branch and waits to become part
   of the next major release.
 
+But sometimes things do not work as planned:
+
+. If a mailing list discussion convinces you that your changes aren't
+  ideal, please explicitly retract the topic to save the maintainer
+  time and effort.
+
+. If you must drop a topic due to shifting priorities, lack of time,
+  or other commitments, notify the list as a courtesy so others can
+  take over. Anyone can resurrect the topic later when they have the
+  capacity to do so.
+
+. Topics with unaddressed review comments that remain inactive for
+  four weeks may be discarded by the maintainer.
+
 In the following sections, many techniques and conventions are listed
 to help your patches get reviewed effectively in such a life cycle.
 
-- 
2.55.0-302-gdbd766b094

Re: [PATCH v2] SubmittingPatches: document how to retract a topic

[Michael Montalbo]

On Wed, Jul 08, 2026 at 10:09:49AM -0700, Junio C Hamano wrote:
> While this document outlines an idealized lifecycle where an author
> develops a patch, refines it with reviewer feedback, and
> successfully merges it into Git, reality is rarely so seamless.
> 
> Sometimes, a topic must be abandoned. Doing so explicitly is far
> better than leaving it in limbo, especially since topics can always
> be resurrected later.
> 
> Clearly state that we encourage contributors to retract any topic
> that does not pan out.
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> 
>  * Added the third bullet that talks about when and how a topic
>    becomes stalled and discarded.
> 
>  Documentation/SubmittingPatches | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
> 
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index d2d82eb543..c269e474e3 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -123,6 +123,20 @@ of review.
>    top, it gets merged to the 'master' branch and waits to become part
>    of the next major release.
>  
> +But sometimes things do not work as planned:
> +
> +. If a mailing list discussion convinces you that your changes aren't
> +  ideal, please explicitly retract the topic to save the maintainer
> +  time and effort.
> +
> +. If you must drop a topic due to shifting priorities, lack of time,
> +  or other commitments, notify the list as a courtesy so others can
> +  take over. Anyone can resurrect the topic later when they have the
> +  capacity to do so.
> +
> +. Topics with unaddressed review comments that remain inactive for
> +  four weeks may be discarded by the maintainer.
> +

Nice, I think these points read smoothly and the additional "four weeks
until may be discarded" guidance is helpful.

LGTM.

Re: [PATCH] SubmittingPatches: abandoning a series

[Michael Montalbo]

Junio C Hamano <gitster@pobox.com> writes:
> +  A discussion on the list might convince you that your changes are
> +  not such a good idea, in which case you are expected to explicitly
> +  retract the topic, to releave the maintainer from having to worry
> +  about it.

s/releave/relieve/

Also, I might reflow the end:
...in which case you are expected to explicitly retract the topic and
relieve the maintainer from having to worry about it.

> ...It is a friendly thing to do to tell the list in such a case...

Again a slight reflow suggestion (ofc my own subjective taste):
"...As a courtesy, tell the list in such a case so that..."

Finally, maybe a rule of thumb as to how old a topic a topic should get
before a "staleness" update is provided would be helpful, or maybe that
is too contextually dependent / would potentially introduce some
unwanted scheduling contract?

Overall, I think the explicit guidance is helpful. Of course, an author
whose topic is going stale may not be on top of updating its status,
stale or otherwise, by definition. However, I think providing this advice
up-front will encourage authors to be more proactive about taking action
(notify of abandonment / handoff) before a topic gets too old.

Re: [PATCH] SubmittingPatches: abandoning a series

[Junio C Hamano]

Michael Montalbo <mmontalbo@gmail.com> writes:

> Junio C Hamano <gitster@pobox.com> writes:
>> +  A discussion on the list might convince you that your changes are
>> +  not such a good idea, in which case you are expected to explicitly
>> +  retract the topic, to releave the maintainer from having to worry
>> +  about it.

...

Thanks for improvements.

> Finally, maybe a rule of thumb as to how old a topic a topic should get
> before a "staleness" update is provided would be helpful, or maybe that
> is too contextually dependent / would potentially introduce some
> unwanted scheduling contract?
>
> Overall, I think the explicit guidance is helpful.

I've been working on streamlining my workflow to manage the "What's
cooking" report, and writing down guidelines with concrete numbers.

 * When the discussion seems to reach rough consensus that the
   latest round looks good for 'next', the topic is immediately
   marked as "Will merge to 'next'?" in my draft copy (note: I do
   not want to spam the list with "What's cooking" too often, but it
   is the document I work from, and it is updated multiple times a
   day).

 * After no negative opinions are seen on a topic in "Will merge to
   'next'?" state for about 36 hours, the topic is marked as "Will
   merge to 'next'".  I will merge such topics during the next
   integration cycle (note: I can only have up to two integration
   cycles per day due to time constraints).

 * Imagine that a topic was last updated more than 4 weeks ago.  If
   there are review comments on the topic that are left unanswered
   by the author for more than a week, and if nothing happens in the
   discussion thread other than inquiry on the current status, the
   topic is marked as "stalled".  I will try to notice and ping a
   stalled topic once or twice, but after that I may discard such a
   topic (which by the way I really hate having to decide to do so).

 * After a topic is merged to 'next', if nothing negative that needs
   fixing is discovered for 7 calendar days, the topic is merged to
   'master'.  I may shorten this depending on how complex the topic
   is.

THere may be more, but these are what I can think of offhand.

Re: [PATCH] SubmittingPatches: abandoning a series

[Weijie Yuan]

On Tue, Jul 07, 2026 at 09:52:14PM -0700, Junio C Hamano wrote:
> Michael Montalbo <mmontalbo@gmail.com> writes:
> [...]
> > Finally, maybe a rule of thumb as to how old a topic a topic should get
> > before a "staleness" update is provided would be helpful, or maybe that
> > is too contextually dependent / would potentially introduce some
> > unwanted scheduling contract?
> >
> > Overall, I think the explicit guidance is helpful.
> 
> I've been working on streamlining my workflow to manage the "What's
> cooking" report, and writing down guidelines with concrete numbers.
> 
>  * When the discussion seems to reach rough consensus that the
>    latest round looks good for 'next', the topic is immediately
>    marked as "Will merge to 'next'?" in my draft copy (note: I do
>    not want to spam the list with "What's cooking" too often, but it
>    is the document I work from, and it is updated multiple times a
>    day).
> 
>  * After no negative opinions are seen on a topic in "Will merge to
>    'next'?" state for about 36 hours, the topic is marked as "Will
>    merge to 'next'".  I will merge such topics during the next
>    integration cycle (note: I can only have up to two integration
>    cycles per day due to time constraints).
> 
>  * Imagine that a topic was last updated more than 4 weeks ago.  If
>    there are review comments on the topic that are left unanswered
>    by the author for more than a week, and if nothing happens in the
>    discussion thread other than inquiry on the current status, the
>    topic is marked as "stalled".  I will try to notice and ping a
>    stalled topic once or twice, but after that I may discard such a
>    topic (which by the way I really hate having to decide to do so).
> 
>  * After a topic is merged to 'next', if nothing negative that needs
>    fixing is discovered for 7 calendar days, the topic is merged to
>    'master'.  I may shorten this depending on how complex the topic
>    is.
> 
> There may be more, but these are what I can think of offhand.

Integrating the above parts into the document seems like a good idea.

btw, do we need to synchronize MyFirstContribution simultaneously?

Quoting Patrick's words [1]:

Overall it's a bit on the annoying side that we have to always make sure
to update both SubmittingPatches and MyFirstContribution in tandem.
Makes me wonder whether they are mostly redundant and whether it would
make sense to eventually merge them.

Thanks,
Weijie

[1] https://lore.kernel.org/git/ai_7Wh7hrD8PZozg@pks.im/

Re: [PATCH] SubmittingPatches: abandoning a series

[Junio C Hamano]

Weijie Yuan <wy@wyuan.org> writes:

> On Tue, Jul 07, 2026 at 09:52:14PM -0700, Junio C Hamano wrote:
>> Michael Montalbo <mmontalbo@gmail.com> writes:
>> [...]
>> > Finally, maybe a rule of thumb as to how old a topic a topic should get
>> > before a "staleness" update is provided would be helpful, or maybe that
>> > is too contextually dependent / would potentially introduce some
>> > unwanted scheduling contract?
>> >
>> > Overall, I think the explicit guidance is helpful.
>> 
>> I've been working on streamlining my workflow to manage the "What's
>> cooking" report, and writing down guidelines with concrete numbers.
>> 
>>  * When the discussion seems to reach rough consensus that the
>>    latest round looks good for 'next', the topic is immediately
>>    marked as "Will merge to 'next'?" in my draft copy (note: I do
>>    not want to spam the list with "What's cooking" too often, but it
>>    is the document I work from, and it is updated multiple times a
>>    day).
>> 
>>  * After no negative opinions are seen on a topic in "Will merge to
>>    'next'?" state for about 36 hours, the topic is marked as "Will
>>    merge to 'next'".  I will merge such topics during the next
>>    integration cycle (note: I can only have up to two integration
>>    cycles per day due to time constraints).
>> 
>>  * Imagine that a topic was last updated more than 4 weeks ago.  If
>>    there are review comments on the topic that are left unanswered
>>    by the author for more than a week, and if nothing happens in the
>>    discussion thread other than inquiry on the current status, the
>>    topic is marked as "stalled".  I will try to notice and ping a
>>    stalled topic once or twice, but after that I may discard such a
>>    topic (which by the way I really hate having to decide to do so).
>> 
>>  * After a topic is merged to 'next', if nothing negative that needs
>>    fixing is discovered for 7 calendar days, the topic is merged to
>>    'master'.  I may shorten this depending on how complex the topic
>>    is.
>> 
>> There may be more, but these are what I can think of offhand.
>
> Integrating the above parts into the document seems like a good idea.

It could be, but not to the document we are discussing.  The current
document is about contributor's guide, telling them what to do and
how, and "'next' usually holds a topic for 7 days" is not as
interesting.

> btw, do we need to synchronize MyFirstContribution simultaneously?
>
> Quoting Patrick's words [1]:
>
> Overall it's a bit on the annoying side that we have to always make sure
> to update both SubmittingPatches and MyFirstContribution in tandem.
> Makes me wonder whether they are mostly redundant and whether it would
> make sense to eventually merge them.

Surely, but that is outside the scope of this patch.

Thanks.

Re: [PATCH] SubmittingPatches: abandoning a series

[Weijie Yuan]

Hi Michael,

By the way, off-topic:

I noticed that several times your replies didn't carry with a
"In-Reply-To" header, which made me confused about the threads when
surfing on the web interface of lore.kernel.org. So also, I cannot pull
down the complete thread with b4. If possible, you may check your email
clients, though all email clients suck ;-)

Thanks,
Weijie

Re: [PATCH] SubmittingPatches: abandoning a series

[Michael Montalbo]

On Tue, Jul 7, 2026 at 10:27 PM Weijie Yuan <wy@wyuan.org> wrote:
>
> Hi Michael,
>
> By the way, off-topic:
>
> I noticed that several times your replies didn't carry with a
> "In-Reply-To" header, which made me confused about the threads when
> surfing on the web interface of lore.kernel.org. So also, I cannot pull
> down the complete thread with b4. If possible, you may check your email
> clients, though all email clients suck ;-)
>

Argh, sorry about that :(

I think my workflow for replying to threads I am not already a part of is
flawed. I usually control-click the reply mailto: link on the message in
lore.kernel.org/git. That launches Gmail then I manually craft a message
and send from there. I will spend some time investigating my workflow
more deeply.

Thank you for the helpful note!

Re: [PATCH] SubmittingPatches: abandoning a series

[Weijie Yuan]

On Tue, Jul 07, 2026 at 10:41:53PM -0700, Michael Montalbo wrote:
> I think my workflow for replying to threads I am not already a part of is
> flawed. I usually control-click the reply mailto: link on the message in
> lore.kernel.org/git. That launches Gmail then I manually craft a message
> and send from there. I will spend some time investigating my workflow
> more deeply.

I guess you are right. I suspect the Gmail web interface is the reason
why the In-Reply-To header was lost here.

> Thank you for the helpful note!

You´re welcome!