From patchwork Wed May 8 11:29:59 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Christopher Baines X-Patchwork-Id: 64137 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 9E4A627BBEA; Wed, 8 May 2024 12:30:50 +0100 (BST) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-2.9 required=5.0 tests=BAYES_00,MAILING_LIST_MULTI, SPF_HELO_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id 9D90227BBE2 for ; Wed, 8 May 2024 12:30:49 +0100 (BST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s4fVQ-0007c3-26; Wed, 08 May 2024 07:30:40 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s4fVO-0007br-76 for guix-patches@gnu.org; Wed, 08 May 2024 07:30:38 -0400 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1s4fVN-0007M3-8G; Wed, 08 May 2024 07:30:37 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1s4fVl-0007qe-P3; Wed, 08 May 2024 07:31:01 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#70549] [PATCH v2] doc: Make changes to the handling of branches. References: <94192a7b7eb8d2dc5008c20abcc3940b4474d800.1713964129.git.mail@cbaines.net> In-Reply-To: <94192a7b7eb8d2dc5008c20abcc3940b4474d800.1713964129.git.mail@cbaines.net> Resent-From: Christopher Baines Original-Sender: "Debbugs-submit" Resent-CC: pelzflorian@pelzflorian.de, ludo@gnu.org, guix-patches@gnu.org Resent-Date: Wed, 08 May 2024 11:31:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 70549 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 70549@debbugs.gnu.org Cc: Florian Pelz , Ludovic =?utf-8?q?Court=C3=A8?= =?utf-8?q?s?= X-Debbugs-Original-Xcc: Florian Pelz , Ludovic =?utf-8?q?Court=C3=A8s?= Received: via spool by 70549-submit@debbugs.gnu.org id=B70549.171516783226391 (code B ref 70549); Wed, 08 May 2024 11:31:01 +0000 Received: (at 70549) by debbugs.gnu.org; 8 May 2024 11:30:32 +0000 Received: from localhost ([127.0.0.1]:48348 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1s4fVI-0006q1-1j for submit@debbugs.gnu.org; Wed, 08 May 2024 07:30:32 -0400 Received: from mira.cbaines.net ([212.71.252.8]:43422) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1s4fVD-0006bV-9f for 70549@debbugs.gnu.org; Wed, 08 May 2024 07:30:31 -0400 Received: from localhost (unknown [212.132.255.10]) by mira.cbaines.net (Postfix) with ESMTPSA id 91D8327BBE2 for <70549@debbugs.gnu.org>; Wed, 8 May 2024 12:30:00 +0100 (BST) Received: from localhost (localhost [local]) by localhost (OpenSMTPD) with ESMTPA id a1c11969 for <70549@debbugs.gnu.org>; Wed, 8 May 2024 11:30:00 +0000 (UTC) From: Christopher Baines Date: Wed, 8 May 2024 12:29:59 +0100 Message-ID: <112222932424e4b346500995cbfd5866ef30b732.1715167799.git.mail@cbaines.net> X-Mailer: git-send-email 2.41.0 MIME-Version: 1.0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches Require that you create a "Request to merge" issue when you create a branch, rather than when you wish to merge it. This should help avoid this step being missed. Also, add information on how to manage these branches: 1. Suggest creating the branch from patches, rather than having a stateful branch, since this should help to reduce complexity and avoid merges. 2. Require that branches don't have unnecessary changes, since this increases the risks of conflicts with other branches. 3. Suggest that the branch not be stateful, and it's just a combination of patches. 4. Suggest avoiding merges since these create a more complicated Git history. 5. Suggest that the branch be up to date before merging, as this helps avoid the combination of master plus the branch differing significantly from the branch alone. Finally, require that the branch be deleted once they're merged. This prepares for the branch being created again. * doc/contributing.texi (Managing Patches and Branches): Make changes to the handling of branches. Change-Id: Ib9419c6df94f485475bd6f147e82ea254e76cec2 --- doc/contributing.texi | 68 ++++++++++++++++++++++++++++++++----------- 1 file changed, 51 insertions(+), 17 deletions(-) base-commit: 2bea3f256209c4f92a2ace28b45d1f452a2b51ba diff --git a/doc/contributing.texi b/doc/contributing.texi index 66f4e86d0a..ecff6300bf 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -2298,9 +2298,9 @@ Managing Patches and Branches @cindex feature branches, coordination 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}). The title of the issue requesting to merge a branch -should have the following format: +guix-patches issue each time you create a branch (@pxref{The Issue +Tracker}). The title of the issue requesting to merge a branch should +have the following format: @cindex merge requests, template @example @@ -2308,20 +2308,51 @@ Managing Patches and Branches @end example The @url{https://qa.guix.gnu.org/, QA infrastructure} recognizes such -issues and lists the merge requests on its main page. 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@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.} which other issues. -Therefore, to know which branch is at the front of the queue, look for -the oldest issue, or the issue that isn't @dfn{blocked} by any other -branch merges. An ordered list of branches with the open issues is -available at @url{https://qa.guix.gnu.org}. +issues and lists the merge requests on its main page. The following +points apply to managing these branches: + +@enumerate +@item +The commits on the branch should be a combination of the patches +relevant to the branch. Patches not related to the topic of the branch +should go elsewhere. + +@item +Any changes that can be made on the master branch, should be made on the +master branch. If a commit can be split to apply part of the changes on +master, this is good to do. + +@item +It should be possible to re-create the branch by starting from master +and applying the relevant patches. + +@item +Avoid merging master in to the branch. Prefer rebasing or re-creating +the branch on top of an updated master revision. + +@item +Minimise the changes on master that are missing on the branch prior to +merging the branch in to master. This means that the state of the +branch better reflects the state of master should the branch be merged. + +@item +If you don't have commit access, create the ``Request for merging'' +issue and request that someone creates the branch. Include a list of +issues/patches to include on the branch. +@end enumerate + +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@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.} which other issues. Therefore, to know which +branch is at the front of the queue, look for the oldest issue, or the +issue that isn't @dfn{blocked} by any other branch merges. An ordered +list of branches with the open issues is available at +@url{https://qa.guix.gnu.org}. 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 @@ -2329,6 +2360,9 @@ Managing Patches and Branches @indicateurl{https://qa.guix.gnu.org/branch/@var{branch}} to see information on some builds and substitute availability. +Once the branch has been merged, the issue should be closed and the +branch deleted. + @node Debbugs User Interfaces @subsection Debbugs User Interfaces