[PATCH] doc: Make changes to the handling of branches.

  • Done
  • quality assurance status badge
Details
6 participants
  • Andreas Enge
  • Efraim Flashner
  • Ludovic Courtès
  • Christopher Baines
  • Steve George
  • Simon Tournier
Owner
unassigned
Submitted by
Christopher Baines
Severity
normal
C
C
Christopher Baines wrote on 24 Apr 15:08 +0200
(address . guix-patches@gnu.org)
94192a7b7eb8d2dc5008c20abcc3940b4474d800.1713964129.git.mail@cbaines.net
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(-)

Toggle diff (88 lines)
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@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@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
C
C
Christopher Baines wrote on 24 Apr 15:21 +0200
Managing patches and branches, retrospective and futher changes?
87o79yvqtn.fsf@cbaines.net
Hey!

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


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.


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


Let me know if you have any thoughts or questions!

Thanks,

Chris
-----BEGIN PGP SIGNATURE-----

iQKlBAEBCgCPFiEEPonu50WOcg2XVOCyXiijOwuE9XcFAmYpB3RfFIAAAAAALgAo
aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldDNF
ODlFRUU3NDU4RTcyMEQ5NzU0RTBCMjVFMjhBMzNCMEI4NEY1NzcRHG1haWxAY2Jh
aW5lcy5uZXQACgkQXiijOwuE9XdQnA//Snz4ZWMeR3pJ8fyzclxc6tNUX1Q9gZGU
4kZaYQT/S/XnG53cSRPJxawnwWCli9ylv3piD0Xr8ZltfPomnZv8bKLztygEyCkD
gwQnOF4oxLIcSWKG5vsrIAdhDlY4XHhj+HPa55DQSfSqKaYfwWdMy35vXUiSInOw
3B07dPCrOAqMGwGVMPjDLm238hpFE2L0jQi93vFdCrIIueeKnNwhwWVmeZTxYALA
ifMDwP3EugH8Djq6abweBIpEVY+g1915y/S4i2H8GirgqDfA+Hd1GGIFR6mr+d8e
zaAcPyupYNwy/lzHRQkCwjCy/OWg3PabDQfADV9k/z2dsEB7+RVOdu93wwy9UF07
YNsBnsHA4MHsXsyj9hpWcHEWOsjuFhHnYDYW13Zlo8YdmncyTl/NMnXmMXeTjhMM
qN5pbABSbWdHu9gExUrhTZJD60AwDfv/o4k6JkI5lYHrmrNwWRsL/lptbKRZB6NM
BnezEQik7/v8Nqldb8pxO7rVqdKK5RLl3XnktgGxW63mKaRGBxwjsQt2N/CsZ9Xh
Bs7ypyu2kAYEY97ZNmRbcmBrPDN1GdfXe9Pi6IeqQGaOHtTLmTjxzAsx7TL0+qFa
tWYZ8nGac3RaWckUQYSpW0JiguytQIEHZaUO9n30/z3xDX3nz5uTbfRCni8f0scZ
CcrOdP/RqYo=
=yr/d
-----END PGP SIGNATURE-----

S
S
Steve George wrote on 25 Apr 09:29 +0200
(name . Christopher Baines)(address . mail@cbaines.net)
tunyb6mbzarwk4nvliv6ruqumftkyaprgsa37ndpjkb3e4ct26@iat5utrstgrl
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:
Toggle quote (25 lines)
> 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
C
C
Christopher Baines wrote on 25 Apr 20:28 +0200
(name . Steve George)(address . steve@futurile.net)
87il05uwiu.fsf@cbaines.net
Steve George <steve@futurile.net> writes:

Toggle quote (4 lines)
> 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.

Toggle quote (4 lines)
> 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.

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

I'm not quite sure what you mean here?

Thanks,

Chris
-----BEGIN PGP SIGNATURE-----

iQKlBAEBCgCPFiEEPonu50WOcg2XVOCyXiijOwuE9XcFAmYqoNlfFIAAAAAALgAo
aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldDNF
ODlFRUU3NDU4RTcyMEQ5NzU0RTBCMjVFMjhBMzNCMEI4NEY1NzcRHG1haWxAY2Jh
aW5lcy5uZXQACgkQXiijOwuE9XfLrw//ebu+GxC3icjTU6qSjdU12k7zfJYlW7aN
oH6iY9IWc3+6MYvRq4g8rHcFVIrdeW9f1N63+9tTNweioIMMC2wYLyssW1rx3QEk
9t7ts8RrgR7xssa3/XngyaVu9mS+3XxvEOqPonsn7Ryj1LlaHE6rgUPVVqJtrokU
mDkzQGN+5nxckIkqR3vakpQSxABUNAxPrhrj8kGm0NRbwbEF5GgxRhGPi+kavx+Y
8XdodN3z6CHsCccM56i26caaCbqtiJwUcFcQM+w48G0tKO7HLCupBNdgVMWO5cbs
izaaGriEEKFveB/7oBtucQw168gKxKJI9Q7OFK8uzPm83p2j4c/vBcd7p8qbNWb+
TMzZEi4Q/UGCvAYfi1XjKmNebB8yvMVe5/T9xsevqL3FQ6JdSek3NwnT9XAdKeKn
J/2Ilpe6ZvTluARdetq1ru11yXqv7Z4rwnYnf1VYKTXjq5U5BXfF4zDcsdWS0nSl
Yus/f80hmoZCnpMTOB4Kq2Jm21Nh7jTpNRsQ0s2gm3nEBUhXav25JR8yGAHq2+Tl
76JZa/sb+IHynePcd6lLeJsgnGHSbHgHeC74nx+ECDplDDu4Hwajhjy8ZDYpk8DC
egtxpLIOaJITnXe38rDP+jsA9KomC2JIamv9/3D+JlMlx9npUOOD7HV3QuhzqFxa
kOW0dC+wckg=
=xj0Z
-----END PGP SIGNATURE-----

E
E
Efraim Flashner wrote on 26 Apr 18:03 +0200
(name . Christopher Baines)(address . mail@cbaines.net)
ZivQbNjJvVKtGAzE@pbp
On Wed, Apr 24, 2024 at 02:21:56PM +0100, Christopher Baines wrote:
Toggle quote (12 lines)
> 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.

Toggle quote (16 lines)
>
> 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@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
-----BEGIN PGP SIGNATURE-----

iQIzBAABCAAdFiEEoov0DD5VE3JmLRT3Qarn3Mo9g1EFAmYr0GsACgkQQarn3Mo9
g1EEwg/9GFu+h7vylBRFLjdddWZR713wRSsc1BN6V/9FMMUCnVjCXCX4hTcvbqcF
RbUhwP3O31Ui3JyJOTOA51KwNCracsHrUJJjgVxaVNs8VBKCqayxOjQdwoLBqnPu
EyETqadg1ZPltYLDE/bHad27ZaKeG69gTtPFW7bgiUycSL8HZis8+CxHFTbcT7cU
bOGxHF5Q+VVzYlSz5mDoDm0V7hE4gb93zD3eCBCptLEX9OWoP5a14WnHEF08vy/t
659PZdbndVA6wygtr94xPbaJE7oIfHOvsCGwvmdbYl/JyrHnaXk2i9A6S+6Whr7g
5A1LQDZqIrmHrn+9BT0c4mT4D8mD/ePyzDs2dtShKj9/sMpitz2JqIigP+JPya+d
enVwmx3myHWu79e6i35Rmoh1yl6UQo5jsSF7ViHHStwVRxDE18JGXLcbde2qnbcd
6wt8F8SwXonZge+zqd8WJuicgIWbg/5gdqmVxztIQ++N/UyY5JKZBOEEgFeJmfo1
juN69Uu5KDQgsTMT7d21IBa+JmJqx7SipSvKX4kf0XTHcNOLT7DLVdZTsInPuvoW
qsn/Nqn4v/0OdTyyaTedXQsI419QDLMqi4L+stPed5k+MtM0yN0weDaMTb2P2pg4
t93HFCPgMahQQr3eeXEJ74r33nOIZFZZeoHu0GnVkPPOywE34ag=
=pXQy
-----END PGP SIGNATURE-----


A
A
Andreas Enge wrote on 29 Apr 15:24 +0200
(name . Christopher Baines)(address . mail@cbaines.net)
Zi-ff4xC0teYgXsf@jurong
Hello,

Am Wed, Apr 24, 2024 at 02:21:56PM +0100 schrieb Christopher Baines:
Toggle quote (2 lines)
> 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
C
C
Christopher Baines wrote on 29 Apr 16:42 +0200
(name . Andreas Enge)(address . andreas@enge.fr)
87a5lcz0vp.fsf@cbaines.net
Andreas Enge <andreas@enge.fr> writes:

Toggle quote (16 lines)
> 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.
-----BEGIN PGP SIGNATURE-----

iQKlBAEBCgCPFiEEPonu50WOcg2XVOCyXiijOwuE9XcFAmYvscpfFIAAAAAALgAo
aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldDNF
ODlFRUU3NDU4RTcyMEQ5NzU0RTBCMjVFMjhBMzNCMEI4NEY1NzcRHG1haWxAY2Jh
aW5lcy5uZXQACgkQXiijOwuE9XdsoQ/9GePG2du8EvHLSiEZs0Z0jV18C0rRcxsZ
U9yDOqrNs16kAiroF+/p6EMQ2vaSWmCKS5JeHGyunrmlybSWA98I2bRF97V986XY
kO6BMyRFSpkr7B6y8gM943PJt5i7DtBk3T+Z/OCwagSP9nfp0rwfQIlIaL6DRHe/
tv99bgBpPscExoEKcwqGKqEG/Bp0YddXqbszpTRIi0qA+jDAvkDA0QQnyfviirXp
NoAFZtIyFBXh2+c+PNbjxJn8UCoWpV3WpMSrPKai02zulu86wIYG0q5V4UGG26ox
Ow8uXvkl0Nao1enDcBog6ILMpk9vl+9qjdnalGlS+r2RK4W9P0M0gjWh6N4Yrkjq
xhHnrJr8oQZ8kgkopJT4A2G6Ai2zo86KJcgK9BIwRAnGMcCxjOUu0fjst0WB9VCJ
gbIOGJtlO7WuHCx+YQIHQx5dvYYtqqIG1Iv+cBkv8UxIZtFaN6wcRF1Lremrg6s1
G/yjX6ljiiCQUqpKjfAETvQ26TUcQFdUQtq4VO9Wib5p4sUjsWDx+DJB9ymHDIgE
48nIuwf7WrqunwEYO028wzUrk24FOyyQZZLIvMpxzc7XR1E8xnmm0nrZZhYV1Zz1
uIb+K532iePkdS2S4tr5r57pOAIgDmZ32I+sGdtNcyUEYGspDymOAbhD4OuNe1Kz
qXCgIAuP/VM=
=2IS/
-----END PGP SIGNATURE-----

L
L
Ludovic Courtès wrote on 1 May 18:20 +0200
Re: [bug#70549] [PATCH] doc: Make changes to the handling of branches.
(name . Christopher Baines)(address . mail@cbaines.net)(address . 70549@debbugs.gnu.org)
874jbh5wra.fsf@gnu.org
Hi,

Christopher Baines <mail@cbaines.net> skribis:

Toggle quote (4 lines)
> 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:

Toggle quote (5 lines)
> 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.

[...]

Toggle quote (8 lines)
> 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?

Toggle quote (4 lines)
> +@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.”

Toggle quote (9 lines)
> +@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’.
C
C
Christopher Baines wrote on 1 May 19:07 +0200
(name . Ludovic Courtès)(address . ludo@gnu.org)(address . 70549@debbugs.gnu.org)
87jzkdv4t9.fsf@cbaines.net
Ludovic Courtès <ludo@gnu.org> writes:

Toggle quote (11 lines)
>> 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.

Toggle quote (7 lines)
>> +@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.

Toggle quote (11 lines)
>> +@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
-----BEGIN PGP SIGNATURE-----

iQKlBAEBCgCPFiEEPonu50WOcg2XVOCyXiijOwuE9XcFAmYyduNfFIAAAAAALgAo
aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldDNF
ODlFRUU3NDU4RTcyMEQ5NzU0RTBCMjVFMjhBMzNCMEI4NEY1NzcRHG1haWxAY2Jh
aW5lcy5uZXQACgkQXiijOwuE9XdCtQ/9F2NLJJai6GbdHNb4fqlZvFnKi6bsGTEy
NI9BpFXEUe1Plp7rds3ZLCsW+itLvoFNJpengmrySsj/tPum/gWlEPwLyY/omtz3
05NZW0Xt16Ij0pHnKA/o5Xt8oZgBAEzsg33pgS8/uBFZcmFWebMFGvd/znTev2Xo
MJPlnrb0pgS+9noqB8DRcYaEe3uea5PLiS+JyEqOkzBNfp78JwJV5pbyYt6HEFOJ
1dKfiPUTLywIqjN6xhEDfuPNYUr91CJRXYHVBAK3fvuRCjlYfNo0l/PXk4cz5p0X
QshhDIgEwZ6vJImQgouzmkBqUKxmlOngiF3BLSfKG8m6JoB27oUMGAvzLVa21tNZ
2vtBI2zCdzJHn/XB9wKXhOfS082zrp4nmeHYCkMqu/yXWNDSLk3+BcSxJC6XvfW9
UGJPEQk5HE0OJLJko9uh+LNB60Y/G77iXDcfeNHw30gYJa+ssyWtmNOUf/FXjtzS
S7U4Am1dCRlpp8/5SzIcwIOduNdQQnUF2phdmX7q44ya7WtMwkGpbzJt1yqyZOD0
6mNemQuJNQD/EXRKTqECoYIhTIhynQqyuLfUOD9ROWeHw0TPDNr2aYLXy/ovoPa/
GxlpE7ZC34WSE5j48SjtBIdE2nQNqR7ZwKjYu1gPExzXBMoky+WQX7Z8WNTn2kFB
6/ixkKhkUUM=
=nkZH
-----END PGP SIGNATURE-----

C
C
Christopher Baines wrote on 8 May 13:29 +0200
[PATCH v2] doc: Make changes to the handling of branches.
(address . 70549@debbugs.gnu.org)
112222932424e4b346500995cbfd5866ef30b732.1715167799.git.mail@cbaines.net
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 that the branch not be stateful, and it's just a combination of
patches.

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

5. 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 | 68 ++++++++++++++++++++++++++++++++-----------
1 file changed, 51 insertions(+), 17 deletions(-)

Toggle diff (97 lines)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 66f4e86d0a..ecff6300bf 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -2298,9 +2298,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
@@ -2308,20 +2308,51 @@ 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@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. Patches not related to the topic of the branch
+should go elsewhere.
+
+@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
+It should be possible to re-create the branch by starting from master
+and applying the relevant patches.
+
+@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. This means that the state of the
+branch better reflects the state of master should the branch be merged.
+
+@item
+If you don't have commit access, create the ``Request for merging''
+issue and request that someone creates the branch. Include a list of
+issues/patches to include on the branch.
+@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@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
@@ -2329,6 +2360,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: 2bea3f256209c4f92a2ace28b45d1f452a2b51ba
--
2.41.0
S
S
Simon Tournier wrote on 22 May 16:33 +0200
87o78x3oh6.fsf@gmail.com
Hi,

On mer., 08 mai 2024 at 12:29, Christopher Baines <mail@cbaines.net> wrote:

Toggle quote (8 lines)
> doc/contributing.texi | 68 ++++++++++++++++++++++++++++++++-----------
> 1 file changed, 51 insertions(+), 17 deletions(-)
>
> diff --git a/doc/contributing.texi b/doc/contributing.texi
> index 66f4e86d0a..ecff6300bf 100644
> --- a/doc/contributing.texi
> +++ b/doc/contributing.texi

I am probably a bit late. All this LGTM! :-)

Thank you for this work.

Cheers,
simon
C
C
Christopher Baines wrote on 22 May 18:04 +0200
(address . 70549-done@debbugs.gnu.org)
874japsuia.fsf@cbaines.net
These changes have now been pushed to master as
4955589f2f343e1862dfae7831d1fc548811d59b.
-----BEGIN PGP SIGNATURE-----

iQKlBAEBCgCPFiEEPonu50WOcg2XVOCyXiijOwuE9XcFAmZOF41fFIAAAAAALgAo
aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldDNF
ODlFRUU3NDU4RTcyMEQ5NzU0RTBCMjVFMjhBMzNCMEI4NEY1NzcRHG1haWxAY2Jh
aW5lcy5uZXQACgkQXiijOwuE9XfYoxAAiDTdD5MgGHZihkgP6lHgl9CBc6KzC3sZ
sCPQSZ8Teq7q7NleoHxkV/L08AxBidoBsMCkpazNOJvUucOBkgRvflFvELMBeYg3
Uq+lFYILjz9CGLlSfyBk2lWy2197hcqGH6Plo4lV5utlUw+8v8PKUJghEkN+6xZE
KEcN7ui+XHI+jYU/mktwuEEIlJkgrvvWjRA7PgSdTI+9ISlFSV9bH3xRIx0orAVS
/A3qyhXBSEJLsA9F8O4qyQWzB2CNW1JrYoTxk3w5xlGWl2Nf6/dr9z2oST+IjpHW
gmOYEYXWtZfUu1j64ri5VKZvyZWJn4c2C2/svYJiIMca4ffTG4AgeTkh75Q1z1B+
t2gkDvLUhYpxVNvtDwz4/ONdrYBTyYL0sk3j7aJvQD9TqRiwfIZ7iyLQuJMyC6Gn
U9QpfDtdw9UiKANr345WSCQpg0XKcf1XDl02TEEEwRfaa5YaQdFVYNrG/PBSVr/i
rZGfcp3laMfjaPp+7vUxaXpWt45fHdxXrfhxgNqPQLlb4Djyglj3vvmuIfs5Rfwn
YY3YM2JZOddQ0ZJVppxrpce2340FqPIfAuNH1aigIPAZ4AVD3NeRt0ssVSNIfvY+
5hi8Y1A+ahbeasIKDf5rJ0EMqJ10Dv3Dj83RR75afuKp5coJTRfLj0KFitj8PUm8
ka1eEiTiaFk=
=WJcg
-----END PGP SIGNATURE-----

Closed
?
Your comment

This issue is archived.

To comment on this conversation send an email to 70549@debbugs.gnu.org

To respond to this issue using the mumi CLI, first switch to it
mumi current 70549
Then, you may apply the latest patchset in this issue (with sign off)
mumi am -- -s
Or, compose a reply to this issue
mumi compose
Or, send patches to this issue
mumi send-email *.patch