From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id yNO3H30Wd2SSoQAASxT56A (envelope-from ) for ; Wed, 31 May 2023 11:42:21 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id 0CGPH30Wd2TTLAEAauVa8A (envelope-from ) for ; Wed, 31 May 2023 11:42:21 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id F31E18AFD for ; Wed, 31 May 2023 11:42:20 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1q4ILG-0005xl-LX; Wed, 31 May 2023 05:42:06 -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 1q4ILF-0005xX-Bo for guix-patches@gnu.org; Wed, 31 May 2023 05:42:05 -0400 Received: from debbugs.gnu.org ([209.51.188.43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1q4ILC-0001pw-0p for guix-patches@gnu.org; Wed, 31 May 2023 05:42:05 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1q4ILB-0000Hn-Nv for guix-patches@gnu.org; Wed, 31 May 2023 05:42:01 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#63459] [PATCH v2] doc: Move and rewrite the branching strategy. References: In-Reply-To: Resent-From: Christopher Baines Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Wed, 31 May 2023 09:42:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 63459 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 63459@debbugs.gnu.org Cc: Christopher Baines Received: via spool by 63459-submit@debbugs.gnu.org id=B63459.16855260801049 (code B ref 63459); Wed, 31 May 2023 09:42:01 +0000 Received: (at 63459) by debbugs.gnu.org; 31 May 2023 09:41:20 +0000 Received: from localhost ([127.0.0.1]:34907 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1q4IKV-0000Gq-KS for submit@debbugs.gnu.org; Wed, 31 May 2023 05:41:20 -0400 Received: from mira.cbaines.net ([212.71.252.8]:42582) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1q4IKR-0000GZ-VH for 63459@debbugs.gnu.org; Wed, 31 May 2023 05:41:18 -0400 Received: from localhost (unknown [IPv6:2a02:8010:68c1:0:54d1:d5d4:280e:f699]) by mira.cbaines.net (Postfix) with ESMTPSA id CC20527BBE2; Wed, 31 May 2023 10:41:14 +0100 (BST) Received: from localhost (localhost [local]) by localhost (OpenSMTPD) with ESMTPA id 5f28fabd; Wed, 31 May 2023 09:41:13 +0000 (UTC) From: Christopher Baines Date: Wed, 31 May 2023 10:41:12 +0100 Message-Id: <9e9b6e968ab3faa7281d064cdfc59ef32adcf689.1685526070.git.mail@cbaines.net> X-Mailer: git-send-email 2.40.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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+larch=yhetil.org@gnu.org Sender: guix-patches-bounces+larch=yhetil.org@gnu.org X-Migadu-Country: US X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1685526141; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:resent-cc: resent-from:resent-sender:resent-message-id:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post; bh=LCZUYZMWLRElrDiebQMv3uQu2tJE5vSFwuWG9xZXG74=; b=BHyJuGWZH5FcyPBWgxNQ13TNp0mVoFgHg08J72LpxR340ZuBFknPvZtnZkmubvYal/udFn fW8HNX1XomRWzlBiiWjx70cVMY11R+d6Hs/q6+/oo1A50JEwh3s+1DB+AaFt/EbB4uDNGP zteF67GE9QxV4bcRsJDVABDUncdhmD1uHArwda2krGt3TbPgmM2w9Q7mYtAkRAP+UhpoG2 GBEeUKecL4hcyMFbLPEEvwxj3ribg0nd8qkJyNdHk3GllvtBJb7MZBKebgtfn/qiRIE+BY /RT8tWEkoc6qSzz2iYsIAJSgRRtrrcgfH8tUvIsxX70k459pscxenIdEsj0UtQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" ARC-Seal: i=1; s=key1; d=yhetil.org; t=1685526141; a=rsa-sha256; cv=none; b=oWYiSH5YnmaPCMPhQICGan41SbLOEWqnLmqdKQJINVGSbK6yHNB+QDis9v+0THNAC8UFjM qtKrSl+XvXQ+GZbGtuEnvo4ms11UpFR3yA+ElyVxu/zIk5e98OsiPquXOUR0bty6SCcJ9l NyLkiJVnzOPxu4mGHjM0FRK4H1rIxwOs+gPzshSAeAoHSJs2MFxOcwik2fpMy9McJhX4Tx ZIB4AsWw/gVW7rJsiAjtbxE8wYtAhwsZh9M7bw31m7tpHOTJV6yAFGsUlTZKdpxjp2j+q3 JyFDsiewSEgOtk3BofwVSGVGKjSnCUcCo0o8qSuHW8SKOoKbZxWBRsBMl7itXg== X-Migadu-Scanner: scn1.migadu.com X-Migadu-Spam-Score: 0.85 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: F31E18AFD X-Spam-Score: 0.85 X-TUID: yxil3ipipOH6 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 --- doc/contributing.texi | 140 +++++++++++++++++++++--------------------- doc/guix.texi | 14 ++--- 2 files changed, 76 insertions(+), 78 deletions(-) diff --git a/doc/contributing.texi b/doc/contributing.texi index f692872c04..96b22b7d9a 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -26,7 +26,7 @@ Contributing * Packaging Guidelines:: Growing the distribution. * Coding Style:: Hygiene of the contributor. * Submitting Patches:: Share your work. -* Tracking Bugs and Patches:: Keeping it all organized. +* Tracking Bugs and Changes:: Keeping it all organized. * Commit Access:: Pushing to the official repository. * Updating the Guix Package:: Updating the Guix package definition. * Writing Documentation:: Improving documentation in GNU Guix. @@ -1161,11 +1161,11 @@ Submitting Patches at the section on commit access (@pxref{Commit Access}). This mailing list is backed by a Debbugs instance, which allows us to -keep track of submissions (@pxref{Tracking Bugs and Patches}). Each -message sent to that mailing list gets a new tracking number assigned; -people can then follow up on the submission by sending email to -@code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER} is -the tracking number (@pxref{Sending a Patch Series}). +keep track of submissions (@pxref{Tracking Bugs and Changes}). +Each message sent to that mailing list gets a new tracking number +assigned; people can then follow up on the submission by sending email +to @code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER} +is the tracking number (@pxref{Sending a Patch Series}). Please write commit logs in the ChangeLog format (@pxref{Change Logs,,, standards, GNU Coding Standards}); you can check the commit history for @@ -1257,48 +1257,9 @@ Submitting Patches the @code{texlive-tiny} package or @code{texlive-union} procedure instead. @item -For important changes, check that dependent packages (if applicable) are -not affected by the change; @code{guix refresh --list-dependent -@var{package}} will help you do that (@pxref{Invoking guix refresh}). - -@c See . -@cindex branching strategy -@cindex rebuild scheduling strategy -Depending on the number of dependent packages and thus the amount of -rebuilding induced, commits go to different branches, along these lines: - -@table @asis -@item 300 dependent packages or less -@code{master} branch (non-disruptive changes). - -@item between 300 and 1,800 dependent packages -@code{staging} branch (non-disruptive changes). This branch is intended -to be merged in @code{master} every 6 weeks or so. Topical changes -(e.g., an update of the GNOME stack) can instead go to a specific branch -(say, @code{gnome-updates}). This branch is not expected to be -buildable or usable until late in its development process. - -@item more than 1,800 dependent packages -@code{core-updates} branch (may include major and potentially disruptive -changes). This branch is intended to be merged in @code{master} every -6 months or so. This branch is not expected to be buildable or usable -until late in its development process. -@end table - -All these branches are @uref{https://@value{SUBSTITUTE-SERVER-1}, -tracked by our build farm} and merged into @code{master} once -everything has been successfully built. This allows us to fix issues -before they hit users, and to reduce the window during which pre-built -binaries are not available. - -When we decide to start building the @code{staging} or -@code{core-updates} branches, they will be forked and renamed with the -suffix @code{-frozen}, at which time only bug fixes may be pushed to the -frozen branches. The @code{core-updates} and @code{staging} branches -will remain open to accept patches for the next cycle. Please ask on -the mailing list or IRC if unsure where to place a patch. -@c TODO: It would be good with badges on the website that tracks these -@c branches. Or maybe even a status page. +Check that dependent packages (if applicable) are not affected by the +change; @code{guix refresh --list-dependent @var{package}} will help you +do that (@pxref{Invoking guix refresh}). @item @cindex determinism, of build processes @@ -1574,16 +1535,17 @@ Teams [env]$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -2 @end example -@node Tracking Bugs and Patches -@section Tracking Bugs and Patches +@node Tracking Bugs and Changes +@section Tracking Bugs and Changes -This section describes how the Guix project tracks its bug reports and -patch submissions. +This section describes how the Guix project tracks its bug reports, +patch submissions and topic branches. @menu -* The Issue Tracker:: The official bug and patch tracker. -* Debbugs User Interfaces:: Ways to interact with Debbugs. -* Debbugs Usertags:: Tag reports with custom labels. +* The Issue Tracker:: The official bug and patch tracker. +* Managing Patches and Branches:: How changes to Guix are managed. +* Debbugs User Interfaces:: Ways to interact with Debbugs. +* Debbugs Usertags:: Tag reports with custom labels. @end menu @node The Issue Tracker @@ -1600,6 +1562,51 @@ The Issue Tracker against the @code{guix-patches} package by sending email to @email{guix-patches@@gnu.org} (@pxref{Submitting Patches}). +@cindex branching strategy +@cindex rebuild scheduling strategy +@node Managing Patches and Branches +@subsection Managing Patches and Branches + +Changes should be posted to @email{guix-patches@@gnu.org}. This mailing +list fills the patch-tracking database (@pxref{The Issue Tracker}). It +also allows patches to be picked up and tested by the quality assurance +tooling; the result of that testing eventually shows up on the dashboard +at @indicateurl{https://qa.guix.gnu.org/issue/@var{ISSUE_NUMBER}}, where +@var{ISSUE_NUMBER} is the number assigned by the issue tracker. Leave +time for a review, without committing anything. + +As an exception, some changes considered ``trivial'' or ``obvious'' may +be pushed directly to the @code{master} branch. This includes changes +to fix typos and reverting commits that caused immediate problems. This +is subject to being adjusted, allowing individuals to commit directly on +non-controversial changes on parts they’re familiar with. + +Changes which affect more than 300 dependent packages (@pxref{Invoking +guix refresh}) 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. + +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. + +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 +@dfn{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. + @node Debbugs User Interfaces @subsection Debbugs User Interfaces @@ -1816,23 +1823,14 @@ Commit Access (discussions of the policy can take place on @email{guix-devel@@gnu.org}). -Changes should be posted to @email{guix-patches@@gnu.org}. This mailing -list fills the patch-tracking database (@pxref{Tracking Bugs and -Patches}). It also allows patches to be picked up and tested by the -quality assurance tooling; the result of that testing eventually shows -up on the dashboard at -@indicateurl{https://qa.guix.gnu.org/issue/@var{ISSUE_NUMBER}}, where -@var{ISSUE_NUMBER} is the number assigned by the issue tracker. Leave -time for a review, without committing anything (@pxref{Submitting -Patches}). If you didn’t receive any reply after one week (two weeks -for more significant changes), and if you're confident, it's OK to -commit. +Ensure you're aware of how the changes should be handled +(@pxref{Managing Patches and Branches}) prior to being pushed to the +repository, especially for the @code{master} branch. -As an exception, some changes considered ``trivial'' or ``obvious'' may -be pushed directly. This includes changes to fix typos and reverting -commits that caused immediate problems. This is subject to being -adjusted, allowing individuals to commit directly on non-controversial -changes on parts they’re familiar with. +If you're committing and pushing your own changes, try and wait at least +one week (two weeks for more significant changes) after you send them +for review. After this, if no one else is available to review them and +if you're confident about the changes, it's OK to commit. When pushing a commit on behalf of somebody else, please add a @code{Signed-off-by} line at the end of the commit log message---e.g., diff --git a/doc/guix.texi b/doc/guix.texi index 5fd2449ed5..f93778f358 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -636,18 +636,18 @@ GNU Distribution RYF Talos II mainboard}. This platform is available as a "technology preview": although it is supported, substitutes are not yet available from the build farm (@pxref{Substitutes}), and some packages may fail to -build (@pxref{Tracking Bugs and Patches}). That said, the Guix +build (@pxref{Tracking Bugs and Changes}). That said, the Guix community is actively working on improving this support, and now is a great time to try it and get involved! @item riscv64-linux little-endian 64-bit RISC-V processors, specifically RV64GC, and -Linux-Libre kernel. This platform is available as a "technology preview": -although it is supported, substitutes are not yet available from the -build farm (@pxref{Substitutes}), and some packages may fail to build -(@pxref{Tracking Bugs and Patches}). That said, the Guix community is -actively working on improving this support, and now is a great time to -try it and get involved! +Linux-Libre kernel. This platform is available as a "technology +preview": although it is supported, substitutes are not yet available +from the build farm (@pxref{Substitutes}), and some packages may fail to +build (@pxref{Tracking Bugs and Changes}). That said, the Guix +community is actively working on improving this support, and now is a +great time to try it and get involved! @end table base-commit: 63e5975cac15102e35032d15fcd90e43d5610fa4 prerequisite-patch-id: 3576be703371d049aa43170dc47ec8285b8f739e -- 2.40.1