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

[Ludovic Courtès]

Hi,

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): 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>

Neat!  Only minor comments from me:

> +@cindex branching strategy
> +@cindex rebuild scheduling strategy
> +@node Managing Patches and Branches
> +@subsection Managing Patches and Branches

Index entries should come after the section heading.

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

IMO we’re still missing a footnote explaining how to block an issue.

> +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
> +@dfn{blocked} by any other branch merges.

No need for @dfn the second time.  I think this could also benefit from
concrete instructions (like “go to this URL”) or a cross-reference to
the Debbugs User Guide or something.

Anyway, nothing crucial: overall it LGTM!

Thanks,
Ludo’.