[bug#63459,v3] doc: Move and rewrite the branching strategy.

Move away from using staging and core-updates, and make the strategy
independant of branch names.

Keep the 300 dependent threshold for changes to master, as I don't have any
specific reason to change this.

Most importantly, require using guix-patches issues to coordinate merging of
the branches, as I think that'll address the key issues that have shown up
recently where it's been unclear which branch should be merged next.

* doc/contributing.texi (Submitting Patches): Move the branching strategy to a
new Managing Patches and Branches section.
(Managing Patches and Branches): New section.
(Commit Policy): Simplify through referencing the new Managing Patches and
Branches section.

Signed-off-by: Christopher Baines <mail@cbaines.net>
---
 doc/contributing.texi | 144 +++++++++++++++++++++---------------------
 doc/guix.texi         |  14 ++--
 2 files changed, 80 insertions(+), 78 deletions(-)


base-commit: 91454f54a4bf07030b51d718482416518ba5c9a7
prerequisite-patch-id: 0c60b9c48946553181183bd4a16611a27f6e62bf

Hi Christopher,

Christopher Baines <mail@cbaines.net> writes:

> Move away from using staging and core-updates, and make the strategy
> independant of branch names.
>
> Keep the 300 dependent threshold for changes to master, as I don't have any
> specific reason to change this.
>
> Most importantly, require using guix-patches issues to coordinate merging of
> the branches, as I think that'll address the key issues that have shown up
> recently where it's been unclear which branch should be merged next.
>
> * doc/contributing.texi (Submitting Patches): Move the branching strategy to a
> new Managing Patches and Branches section.
> (Managing Patches and Branches): New section.
> (Commit Policy): Simplify through referencing the new Managing Patches and
> Branches section.

[...]

> +
> +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}).  These issues indicate the order in which the branches
> +should be merged, so take a look at the open issues for merging branches
> +and mark the issue you create as @dfn{blocked} by the issue previously
> +at the back of the queue@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.}.

Maybe by default, since the strategy would be "first come, first
merged", we can forego with the 'block' tags, as issues will already be
posted in the order (and given an increasing number) they should be
merged?  Then the nitty-gritty details of micro-managing block tags can
be mentioned only when they are useful, e.g. ...

> +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 which other issues.  Therefore, to know which branch
> +is at the front of the queue, look for the issue which isn't blocked by
> +any other branch merges.

... here.  Can anyone merge the branches of someone else that posted
them to the tracker but 'hasn't gotten around' to merge them to the repo
(e.g. gone on vacation), although they were fully QA'd, blocking every
other branch merge?

> +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
> +the necessary testing to have happened.

What does that mean concretely?  How can I track the build status of a
change?  Please at least mention the QA badge which is visible from
issues.guix.gnu.org and perhaps other tricks I'm unaware of :-).

Thanks for working on completing the documentation of the new work flow.

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> Hi Christopher,
>
> Christopher Baines <mail@cbaines.net> writes:
>
>> Move away from using staging and core-updates, and make the strategy
>> independant of branch names.
>>
>> Keep the 300 dependent threshold for changes to master, as I don't have any
>> specific reason to change this.
>>
>> Most importantly, require using guix-patches issues to coordinate merging of
>> the branches, as I think that'll address the key issues that have shown up
>> recently where it's been unclear which branch should be merged next.
>>
>> * doc/contributing.texi (Submitting Patches): Move the branching strategy to a
>> new Managing Patches and Branches section.
>> (Managing Patches and Branches): New section.
>> (Commit Policy): Simplify through referencing the new Managing Patches and
>> Branches section.
>
> [...]
>
>> +
>> +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}).  These issues indicate the order in which the branches
>> +should be merged, so take a look at the open issues for merging branches
>> +and mark the issue you create as @dfn{blocked} by the issue previously
>> +at the back of the queue@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.}.
>
> Maybe by default, since the strategy would be "first come, first
> merged", we can forego with the 'block' tags, as issues will already be
> posted in the order (and given an increasing number) they should be
> merged?  Then the nitty-gritty details of micro-managing block tags can
> be mentioned only when they are useful, e.g. ...

That sounds fine to me.

>> +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 which other issues.  Therefore, to know which branch
>> +is at the front of the queue, look for the issue which isn't blocked by
>> +any other branch merges.
>
> ... here.  Can anyone merge the branches of someone else that posted
> them to the tracker but 'hasn't gotten around' to merge them to the repo
> (e.g. gone on vacation), although they were fully QA'd, blocking every
> other branch merge?

I've moved the blocking stuff down.

As for the merging of branches that others have pushed, I'm not sure
there's consensus regarding this. Personally I would like to see this,
being able to merge other committers changes, I raised it on guix-devel
recently [1].

1: https://lists.gnu.org/archive/html/guix-devel/2023-02/msg00263.html

>> +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
>> +the necessary testing to have happened.
>
> What does that mean concretely?  How can I track the build status of a
> change?  Please at least mention the QA badge which is visible from
> issues.guix.gnu.org and perhaps other tricks I'm unaware of :-).

It's intentionally quite high level and non-concrete. Maybe we'll get to
the point in the future where we have more specific requirements to meet
before merging a branch, but I don't think we have that yet.

qa.guix.gnu.org/branch/NAME is linked to above, and I've added another
link to it here. The QA badge currently doesn't work for branches, but
I'd like to get it working.

I've sent a v4 now, thanks for taking a look!

Chris

Hi Chris,

[...]

>>> +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}).  These issues indicate the order in which the branches
>>> +should be merged, so take a look at the open issues for merging branches
>>> +and mark the issue you create as @dfn{blocked} by the issue previously
>>> +at the back of the queue@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.}.
>>
>> Maybe by default, since the strategy would be "first come, first
>> merged", we can forego with the 'block' tags, as issues will already be
>> posted in the order (and given an increasing number) they should be
>> merged?  Then the nitty-gritty details of micro-managing block tags can
>> be mentioned only when they are useful, e.g. ...
>
> That sounds fine to me.

One disadvantage of this is that people must now manually find the
preceding merge requests on the tracker; but if we have some convention
prefix in the subject, e.g. 'MERGE' or similar (it's always implied we
merge to master branch and nowhere else, correct?), that would still
make it easy.  When the tooling (build coordinator) offers a web view of
the branches to be merged that can be linked as well.

So I think it's a LGTM.

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> Hi Chris,
>
> [...]
>
>>>> +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}).  These issues indicate the order in which the branches
>>>> +should be merged, so take a look at the open issues for merging branches
>>>> +and mark the issue you create as @dfn{blocked} by the issue previously
>>>> +at the back of the queue@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.}.
>>>
>>> Maybe by default, since the strategy would be "first come, first
>>> merged", we can forego with the 'block' tags, as issues will already be
>>> posted in the order (and given an increasing number) they should be
>>> merged?  Then the nitty-gritty details of micro-managing block tags can
>>> be mentioned only when they are useful, e.g. ...
>>
>> That sounds fine to me.
>
> One disadvantage of this is that people must now manually find the
> preceding merge requests on the tracker; but if we have some convention
> prefix in the subject, e.g. 'MERGE' or similar (it's always implied we
> merge to master branch and nowhere else, correct?), that would still
> make it easy.  When the tooling (build coordinator) offers a web view of
> the branches to be merged that can be linked as well.

There's already a webpage featuring the branches and corresponding
issues, they feature in a table on [1]. The qa-frontpage makes the
assumption that the issue titles include the string "Request for
merging" and have the branch name in quotes, but that's just because
that was used as the title for [2].

1: https://qa.guix.gnu.org/
2: https://issues.guix.gnu.org/63521

As you say, it would be good to settle on a convention and mandate this
in contributing.texi.

As for where you're merging, yes, I'm assuming you're merging to master
here.

> So I think it's a LGTM.

Great, thanks for taking a look.