[bug#63459] [PATCH] doc: Rewrite the branching strategy.

[Christopher Baines]

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

signature.asc
Description: PGP signature