GNU bug report logs - #70549
[PATCH] doc: Make changes to the handling of branches.

Previous Next

To reply to this bug, email your comments to 70549 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Christopher Baines <mail <at> cbaines.net>
To: guix-patches <at> gnu.org
Subject: [PATCH] doc: Make changes to the handling of branches.
Date: Wed, 24 Apr 2024 14:08:49 +0100

Require that you create a "Request to merge" issue when you create a branch,
rather than when you wish to merge it.  This should help avoid this step being
missed.

Also, add information on how to manage these branches:

 1. Suggest creating the branch from patches, rather than having a stateful
 branch, since this should help to reduce complexity and avoid merges.

 2. Require that branches don't have unnecessary changes, since this increases
 the risks of conflicts with other branches.

 3. Suggest avoiding merges since these create a more complicated Git history.

 4. Suggest that the branch be up to date before merging, as this helps avoid
 the combination of master plus the branch differing significantly from the
 branch alone.

Finally, require that the branch be deleted once they're merged.  This
prepares for the branch being created again.

* doc/contributing.texi (Managing Patches and Branches): Make changes to the
handling of branches.

Change-Id: Ib9419c6df94f485475bd6f147e82ea254e76cec2
---
 doc/contributing.texi | 59 ++++++++++++++++++++++++++++++-------------
 1 file changed, 42 insertions(+), 17 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index ad0f5a8ecd..038ed7d040 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -2290,9 +2290,9 @@ Managing Patches and Branches
 
 @cindex feature branches, coordination
 To help coordinate the merging of branches, you must create a new
-guix-patches issue each time you wish to merge a branch (@pxref{The
-Issue Tracker}).  The title of the issue requesting to merge a branch
-should have the following format:
+guix-patches issue each time you create a branch (@pxref{The Issue
+Tracker}).  The title of the issue requesting to merge a branch should
+have the following format:
 
 @cindex merge requests, template
 @example
@@ -2300,20 +2300,42 @@ Managing Patches and Branches
 @end example
 
 The @url{https://qa.guix.gnu.org/, QA infrastructure} recognizes such
-issues and lists the merge requests on its main page.  Normally branches
-will be merged in a ``first come, first merged'' manner, tracked through
-the guix-patches issues.
-
-If you agree on a different order with those involved, you can track
-this by updating which issues block <at> footnote{You can mark an issue as
-blocked by another by emailing @email{control@@debbugs.gnu.org} with the
-following line in the body of the email: @code{block XXXXX by YYYYY}.
-Where @code{XXXXX} is the number for the blocked issue, and @code{YYYYY}
-is the number for the issue blocking it.} which other issues.
-Therefore, to know which branch is at the front of the queue, look for
-the oldest issue, or the issue that isn't @dfn{blocked} by any other
-branch merges.  An ordered list of branches with the open issues is
-available at @url{https://qa.guix.gnu.org}.
+issues and lists the merge requests on its main page.  The following
+points apply to managing these branches:
+
+@enumerate
+@item
+The commits on the branch should be a combination of the patches
+relevant to the branch.  It should be possible to re-create the branch
+by starting from master and applying the relevant patches.
+
+@item
+Any changes that can be made on the master branch, should be made on the
+master branch.  If a commit can be split to apply part of the changes on
+master, this is good to do.
+
+@item
+Avoid merging master in to the branch.  Prefer rebasing or re-creating
+the branch on top of an updated master revision.
+
+@item
+Minimise the changes on master that are missing on the branch prior to
+merging the branch in to master.  Merging master in to the branch can be
+appropriate for this purpose.
+@end enumerate
+
+Normally branches will be merged in a ``first come, first merged''
+manner, tracked through the guix-patches issues.  If you agree on a
+different order with those involved, you can track this by updating
+which issues block <at> footnote{You can mark an issue as blocked by another
+by emailing @email{control@@debbugs.gnu.org} with the following line in
+the body of the email: @code{block XXXXX by YYYYY}.  Where @code{XXXXX}
+is the number for the blocked issue, and @code{YYYYY} is the number for
+the issue blocking it.} which other issues.  Therefore, to know which
+branch is at the front of the queue, look for the oldest issue, or the
+issue that isn't @dfn{blocked} by any other branch merges.  An ordered
+list of branches with the open issues is available at
+@url{https://qa.guix.gnu.org}.
 
 Once a branch is at the front of the queue, wait until sufficient time
 has passed for the build farms to have processed the changes, and for
@@ -2321,6 +2343,9 @@ Managing Patches and Branches
 @indicateurl{https://qa.guix.gnu.org/branch/@var{branch}} to see
 information on some builds and substitute availability.
 
+Once the branch has been merged, the issue should be closed and the
+branch deleted.
+
 @node Debbugs User Interfaces
 @subsection Debbugs User Interfaces
 

base-commit: e2ba93373a29ddf5d5754368957e89f3b426bb0a
-- 
2.41.0

Message #8 received at 70549 <at> debbugs.gnu.org (full text, mbox):

From: Christopher Baines <mail <at> cbaines.net>
To: guix-devel <at> gnu.org, 70549 <at> debbugs.gnu.org
Subject: Managing patches and branches, retrospective and futher changes?
Date: Wed, 24 Apr 2024 14:21:56 +0100

[Message part 1 (text/plain, inline)]

Hey!

Almost a year ago, the branching strategy was changed [1][2].

1: https://issues.guix.gnu.org/63459
2: https://lists.gnu.org/archive/html/guix-devel/2023-06/msg00024.html

I think these changes have gone OK, we've had ~27 [3] branches merged in
this manor and I think looking back these changes have been
helpful. Coordination and visibility has improved, and we've been able
to build and test more prior to merging.

3: https://issues.guix.gnu.org/search?query=%22Request+for+merging%22

There's still room for more improvement though. The current guidance is
here [4], and I've sent a patch for improvements here [5].

4: https://guix.gnu.org/en/manual/devel/en/html_node/Managing-Patches-and-Branches.html
5: https://issues.guix.gnu.org/70549

Let me know if you have any thoughts or questions!

Thanks,

Chris

[signature.asc (application/pgp-signature, inline)]

Message #11 received at 70549 <at> debbugs.gnu.org (full text, mbox):

From: Steve George <steve <at> futurile.net>
To: Christopher Baines <mail <at> cbaines.net>
Cc: guix-devel <at> gnu.org, 70549 <at> debbugs.gnu.org
Subject: Re: Managing patches and branches, retrospective and futher changes?
Date: Thu, 25 Apr 2024 08:29:20 +0100

Hi,

I think we should strongly recommend against long-running unmerged branches.

Perhaps there could be a recommendation to merge every 3 months.

Could we add any automation to remind people if:

1. a branch has been unmerged for more than 3 months
2. an odd merge takes places (e.g. the core-updates merges)

Thanks,

Steve

On 24 Apr, Christopher Baines wrote:
> Hey!
> 
> Almost a year ago, the branching strategy was changed [1][2].
> 
> 1: https://issues.guix.gnu.org/63459
> 2: https://lists.gnu.org/archive/html/guix-devel/2023-06/msg00024.html
> 
> I think these changes have gone OK, we've had ~27 [3] branches merged in
> this manor and I think looking back these changes have been
> helpful. Coordination and visibility has improved, and we've been able
> to build and test more prior to merging.
> 
> 3: https://issues.guix.gnu.org/search?query=%22Request+for+merging%22
> 
> There's still room for more improvement though. The current guidance is
> here [4], and I've sent a patch for improvements here [5].
> 
> 4: https://guix.gnu.org/en/manual/devel/en/html_node/Managing-Patches-and-Branches.html
> 5: https://issues.guix.gnu.org/70549
> 
> Let me know if you have any thoughts or questions!
> 
> Thanks,
> 
> Chris

Message #14 received at 70549 <at> debbugs.gnu.org (full text, mbox):

From: Christopher Baines <mail <at> cbaines.net>
To: Steve George <steve <at> futurile.net>
Cc: guix-devel <at> gnu.org, 70549 <at> debbugs.gnu.org
Subject: Re: Managing patches and branches, retrospective and futher changes?
Date: Thu, 25 Apr 2024 19:28:41 +0100

[Message part 1 (text/plain, inline)]

Steve George <steve <at> futurile.net> writes:

> I think we should strongly recommend against long-running unmerged branches.
>
> Perhaps there could be a recommendation to merge every 3 months.

My hope is that with these process changes, we won't end up with
long-running branches.

Maybe we could add a recommendation, but I'm not really sure if that
would help. We still want to merge these changes when they and related
things are ready, so it's not really something that can be willed or
commanded to happen.

> Could we add any automation to remind people if:
>
> 1. a branch has been unmerged for more than 3 months

We can have QA highlight how long the issues have been open for, that's
quite easy to do.

> 2. an odd merge takes places (e.g. the core-updates merges)

I'm not quite sure what you mean here?

Thanks,

Chris

[signature.asc (application/pgp-signature, inline)]

Message #17 received at 70549 <at> debbugs.gnu.org (full text, mbox):

From: Efraim Flashner <efraim <at> flashner.co.il>
To: Christopher Baines <mail <at> cbaines.net>
Cc: guix-devel <at> gnu.org, 70549 <at> debbugs.gnu.org
Subject: Re: Managing patches and branches, retrospective and futher changes?
Date: Fri, 26 Apr 2024 19:03:56 +0300

[Message part 1 (text/plain, inline)]

On Wed, Apr 24, 2024 at 02:21:56PM +0100, Christopher Baines wrote:
> Hey!
> 
> Almost a year ago, the branching strategy was changed [1][2].
> 
> 1: https://issues.guix.gnu.org/63459
> 2: https://lists.gnu.org/archive/html/guix-devel/2023-06/msg00024.html
> 
> I think these changes have gone OK, we've had ~27 [3] branches merged in
> this manor and I think looking back these changes have been
> helpful. Coordination and visibility has improved, and we've been able
> to build and test more prior to merging.

I'd like to just say that this (without checking the numbers) is almost
10x the number of merges we had previously with just the
core-updates/staging branch strategy.

> 3: https://issues.guix.gnu.org/search?query=%22Request+for+merging%22
> 
> There's still room for more improvement though. The current guidance is
> here [4], and I've sent a patch for improvements here [5].
> 
> 4: https://guix.gnu.org/en/manual/devel/en/html_node/Managing-Patches-and-Branches.html
> 5: https://issues.guix.gnu.org/70549
> 
> Let me know if you have any thoughts or questions!
> 
> Thanks,
> 
> Chris



-- 
Efraim Flashner   <efraim <at> flashner.co.il>   רנשלפ םירפא
GPG key = A28B F40C 3E55 1372 662D  14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted

[signature.asc (application/pgp-signature, inline)]

Message #20 received at 70549 <at> debbugs.gnu.org (full text, mbox):

From: Andreas Enge <andreas <at> enge.fr>
To: Christopher Baines <mail <at> cbaines.net>
Cc: guix-devel <at> gnu.org, 70549 <at> debbugs.gnu.org
Subject: Re: Managing patches and branches, retrospective and futher changes?
Date: Mon, 29 Apr 2024 15:24:15 +0200

Hello,

Am Wed, Apr 24, 2024 at 02:21:56PM +0100 schrieb Christopher Baines:
> Let me know if you have any thoughts or questions!

in this part:
+@item
+Minimise the changes on master that are missing on the branch prior to
+merging the branch in to master.  Merging master in to the branch can be
+appropriate for this purpose.

I would drop the second sentence. It mildly contradicts the previous
"avoid merging master into the branch". Writing "avoid merging" instead
of "never merge" already allows for some leeway, I would prefer not to
insist on it.

Andreas

Message #23 received at 70549 <at> debbugs.gnu.org (full text, mbox):

From: Christopher Baines <mail <at> cbaines.net>
To: Andreas Enge <andreas <at> enge.fr>
Cc: guix-devel <at> gnu.org, 70549 <at> debbugs.gnu.org
Subject: Re: Managing patches and branches, retrospective and futher changes?
Date: Mon, 29 Apr 2024 15:42:18 +0100

[Message part 1 (text/plain, inline)]

Andreas Enge <andreas <at> enge.fr> writes:

> Hello,
>
> Am Wed, Apr 24, 2024 at 02:21:56PM +0100 schrieb Christopher Baines:
>> Let me know if you have any thoughts or questions!
>
> in this part:
> +@item
> +Minimise the changes on master that are missing on the branch prior to
> +merging the branch in to master.  Merging master in to the branch can be
> +appropriate for this purpose.
>
> I would drop the second sentence. It mildly contradicts the previous
> "avoid merging master into the branch". Writing "avoid merging" instead
> of "never merge" already allows for some leeway, I would prefer not to
> insist on it.

Yeah, maybe it's redundant. I think what I was trying to say is that
minimising the changes against master is a priority, so do this even if
you resort to merging master in to the branch.

[signature.asc (application/pgp-signature, inline)]

Message #26 received at 70549 <at> debbugs.gnu.org (full text, mbox):

From: Ludovic Courtès <ludo <at> gnu.org>
To: Christopher Baines <mail <at> cbaines.net>
Cc: 70549 <at> debbugs.gnu.org
Subject: Re: [bug#70549] [PATCH] doc: Make changes to the handling of branches.
Date: Wed, 01 May 2024 18:20:57 +0200

Hi,

Christopher Baines <mail <at> cbaines.net> skribis:

> Require that you create a "Request to merge" issue when you create a branch,
> rather than when you wish to merge it.  This should help avoid this step being
> missed.

Excellent, I fully support this change!

A couple of questions/comments:

> Also, add information on how to manage these branches:
>
>  1. Suggest creating the branch from patches, rather than having a stateful
>  branch, since this should help to reduce complexity and avoid merges.

[...]

>  To help coordinate the merging of branches, you must create a new
> -guix-patches issue each time you wish to merge a branch (@pxref{The
> -Issue Tracker}).  The title of the issue requesting to merge a branch
> -should have the following format:
> +guix-patches issue each time you create a branch (@pxref{The Issue
> +Tracker}).  The title of the issue requesting to merge a branch should
> +have the following format:

This means someone on the team with commit access explicitly commits the
branch at the time they send the merge request email, right?

> +@item
> +The commits on the branch should be a combination of the patches
> +relevant to the branch.

Perhaps add: “; patches not related to the topic of the branch should go
elsewhere.”

> +@item
> +Avoid merging master in to the branch.  Prefer rebasing or re-creating
> +the branch on top of an updated master revision.
> +
> +@item
> +Minimise the changes on master that are missing on the branch prior to
> +merging the branch in to master.  Merging master in to the branch can be
> +appropriate for this purpose.

s/in to/into/

Thank you!

Ludo’.

Message #29 received at 70549 <at> debbugs.gnu.org (full text, mbox):

From: Christopher Baines <mail <at> cbaines.net>
To: Ludovic Courtès <ludo <at> gnu.org>
Cc: 70549 <at> debbugs.gnu.org
Subject: Re: [bug#70549] [PATCH] doc: Make changes to the handling of branches.
Date: Wed, 01 May 2024 18:07:46 +0100

[Message part 1 (text/plain, inline)]

Ludovic Courtès <ludo <at> gnu.org> writes:

>>  To help coordinate the merging of branches, you must create a new
>> -guix-patches issue each time you wish to merge a branch (@pxref{The
>> -Issue Tracker}).  The title of the issue requesting to merge a branch
>> -should have the following format:
>> +guix-patches issue each time you create a branch (@pxref{The Issue
>> +Tracker}).  The title of the issue requesting to merge a branch should
>> +have the following format:
>
> This means someone on the team with commit access explicitly commits the
> branch at the time they send the merge request email, right?

There's intentionally no mention of teams here, but that's pretty much
it. I'm not intending this to be super strict, like forgetting the issue
then creating it a day or two later is fine.

You mention commit access, and that does make me think that maybe we
should include something saying that if you don't have commit access,
please go ahead and create the issue, and in it ask for the branch to be
created. With the expectation that they'll be someone with commit access
to help with creating and managing the branch.

>> +@item
>> +The commits on the branch should be a combination of the patches
>> +relevant to the branch.
>
> Perhaps add: “; patches not related to the topic of the branch should go
> elsewhere.”

Good idea.

>> +@item
>> +Avoid merging master in to the branch.  Prefer rebasing or re-creating
>> +the branch on top of an updated master revision.
>> +
>> +@item
>> +Minimise the changes on master that are missing on the branch prior to
>> +merging the branch in to master.  Merging master in to the branch can be
>> +appropriate for this purpose.
>
> s/in to/into/

Good spot.

Thanks,

Chris

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.