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

[Ludovic Courtès]

Hello,

Thanks for this initiative!

Christopher Baines <mail@cbaines.net> skribis:

> 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): Rewrite branching strategy.

[...]

> +Changes to packages with 300 dependent packages or less can be pushed to
> +the @code{master} branch.
> +
> +Larger changes should be first pushed to a branch other than
> +@code{master}. This allows for testing and for the build farms to
> +process the changes prior to being pushed to the @code{master} branch.

I’d be more specific:

  Larger changes should first be pushed to a topic branch other than
  @code{master}; the set of changes should be consistent---e.g., ``GNOME
  update'', ``NumPy update'', etc.  This allows for testing: the branch
  will automatically show up at
  @indicateurl{https://qa.guix.gnu.org/branch/@var{branch}}, with an
  indication of its build status on various platforms.

“Automatic” is a bit of an overstatement; that sentence probably needs
to be tweaked.  :-)  But I think it’s good to link to the QA platform to
make things more concrete.

> +To help coordinate the merging of branches, you must create a new
> +guix-patches issue each time you wish to merge a branch. These issues
                                                          ^
+ (@pxref{Tracking Bugs and Patches})

> +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 blocked by the issue previously at the back of the queue.

s/blocked/@dfn{blocked}/

Perhaps add a footnote or paren stating how to “block” an issue in
Debbugs?

> +Normally branches will be merged in a ``first come, first merged''
> +manor, tracked through the guix-patches issues. If you agree a different

s/manor/manner/
s/agree a/agree on a/

> +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.
> +
> +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.

This is a bit technical.  How can I know “which branch is at the front
of the queue”?  Even as a seasoned Debbugs users, I’m not sure what I’m
supposed to do here.  Do you think we could provide ready to use
commands (debbugs.el or ‘mumi’) or at least a sequence of steps to
follow?

Last but not least: two spaces after end-of-sentence period please.  :-)

This is mostly about tweaking words; I think this is a great step
forward, very much in line with what was discussed in February at the
Guix Days.  Thank you!

Ludo’.