@@ -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 <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
-@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.,
@@ -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
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> --- doc/contributing.texi | 140 +++++++++++++++++++++--------------------- doc/guix.texi | 14 ++--- 2 files changed, 76 insertions(+), 78 deletions(-) base-commit: 63e5975cac15102e35032d15fcd90e43d5610fa4 prerequisite-patch-id: 3576be703371d049aa43170dc47ec8285b8f739e