GNU bug report logs - #63459
[PATCH] doc: Rewrite the branching strategy.

Previous Next

Full log

Message #23 received at 63459 <at> debbugs.gnu.org (full text, mbox):

From: Ludovic Courtès <ludo <at> gnu.org>
To: Christopher Baines <mail <at> cbaines.net>
Cc: 63459 <at> debbugs.gnu.org
Subject: Re: bug#63459: [PATCH] doc: Rewrite the branching strategy.
Date: Tue, 06 Jun 2023 17:27:28 +0200

Hi,

Christopher Baines <mail <at> 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 <at> 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’.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.