doc: Move and rewrite the branching strategy.

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>
This commit is contained in:
Christopher Baines 2023-05-31 09:25:12 +01:00
parent 3bea4c0c19
commit 0ea096ae23
No known key found for this signature in database
GPG key ID: 5E28A33B0B84F577
2 changed files with 80 additions and 78 deletions

View file

@ -26,7 +26,7 @@ choice.
* Packaging Guidelines:: Growing the distribution. * Packaging Guidelines:: Growing the distribution.
* Coding Style:: Hygiene of the contributor. * Coding Style:: Hygiene of the contributor.
* Submitting Patches:: Share your work. * 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. * Commit Access:: Pushing to the official repository.
* Updating the Guix Package:: Updating the Guix package definition. * Updating the Guix Package:: Updating the Guix package definition.
* Writing Documentation:: Improving documentation in GNU Guix. * Writing Documentation:: Improving documentation in GNU Guix.
@ -1161,11 +1161,11 @@ readability of patches. Seasoned Guix developers may also want to look
at the section on commit access (@pxref{Commit Access}). at the section on commit access (@pxref{Commit Access}).
This mailing list is backed by a Debbugs instance, which allows us to This mailing list is backed by a Debbugs instance, which allows us to
keep track of submissions (@pxref{Tracking Bugs and Patches}). Each keep track of submissions (@pxref{Tracking Bugs and Changes}).
message sent to that mailing list gets a new tracking number assigned; Each message sent to that mailing list gets a new tracking number
people can then follow up on the submission by sending email to assigned; people can then follow up on the submission by sending email
@code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER} is to @code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER}
the tracking number (@pxref{Sending a Patch Series}). is the tracking number (@pxref{Sending a Patch Series}).
Please write commit logs in the ChangeLog format (@pxref{Change Logs,,, Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
standards, GNU Coding Standards}); you can check the commit history for standards, GNU Coding Standards}); you can check the commit history for
@ -1257,48 +1257,9 @@ and which optional dependencies should be used. In particular, avoid adding
the @code{texlive-tiny} package or @code{texlive-union} procedure instead. the @code{texlive-tiny} package or @code{texlive-union} procedure instead.
@item @item
For important changes, check that dependent packages (if applicable) are Check that dependent packages (if applicable) are not affected by the
not affected by the change; @code{guix refresh --list-dependent change; @code{guix refresh --list-dependent @var{package}} will help you
@var{package}} will help you do that (@pxref{Invoking guix refresh}). 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.
@item @item
@cindex determinism, of build processes @cindex determinism, of build processes
@ -1574,16 +1535,17 @@ $ guix shell -D guix
[env]$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -2 [env]$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -2
@end example @end example
@node Tracking Bugs and Patches @node Tracking Bugs and Changes
@section Tracking Bugs and Patches @section Tracking Bugs and Changes
This section describes how the Guix project tracks its bug reports and This section describes how the Guix project tracks its bug reports,
patch submissions. patch submissions and topic branches.
@menu @menu
* The Issue Tracker:: The official bug and patch tracker. * The Issue Tracker:: The official bug and patch tracker.
* Debbugs User Interfaces:: Ways to interact with Debbugs. * Managing Patches and Branches:: How changes to Guix are managed.
* Debbugs Usertags:: Tag reports with custom labels. * Debbugs User Interfaces:: Ways to interact with Debbugs.
* Debbugs Usertags:: Tag reports with custom labels.
@end menu @end menu
@node The Issue Tracker @node The Issue Tracker
@ -1600,6 +1562,55 @@ email to @email{bug-guix@@gnu.org}, while patch submissions are filed
against the @code{guix-patches} package by sending email to against the @code{guix-patches} package by sending email to
@email{guix-patches@@gnu.org} (@pxref{Submitting Patches}). @email{guix-patches@@gnu.org} (@pxref{Submitting Patches}).
@node Managing Patches and Branches
@subsection Managing Patches and Branches
@cindex branching strategy
@cindex rebuild scheduling strategy
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 theyre 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}). 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
the necessary testing to have happened. For example, you can check
@indicateurl{https://qa.guix.gnu.org/branch/@var{branch}} to see
information on some builds and substitute availability.
@node Debbugs User Interfaces @node Debbugs User Interfaces
@subsection Debbugs User Interfaces @subsection Debbugs User Interfaces
@ -1816,23 +1827,14 @@ If you get commit access, please make sure to follow the policy below
(discussions of the policy can take place on (discussions of the policy can take place on
@email{guix-devel@@gnu.org}). @email{guix-devel@@gnu.org}).
Changes should be posted to @email{guix-patches@@gnu.org}. This mailing Ensure you're aware of how the changes should be handled
list fills the patch-tracking database (@pxref{Tracking Bugs and (@pxref{Managing Patches and Branches}) prior to being pushed to the
Patches}). It also allows patches to be picked up and tested by the repository, especially for the @code{master} branch.
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 didnt receive any reply after one week (two weeks
for more significant changes), and if you're confident, it's OK to
commit.
As an exception, some changes considered ``trivial'' or ``obvious'' may If you're committing and pushing your own changes, try and wait at least
be pushed directly. This includes changes to fix typos and reverting one week (two weeks for more significant changes) after you send them
commits that caused immediate problems. This is subject to being for review. After this, if no one else is available to review them and
adjusted, allowing individuals to commit directly on non-controversial if you're confident about the changes, it's OK to commit.
changes on parts theyre familiar with.
When pushing a commit on behalf of somebody else, please add a 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., @code{Signed-off-by} line at the end of the commit log message---e.g.,

View file

@ -637,18 +637,18 @@ includes POWER9 systems such as the
RYF Talos II mainboard}. This platform is available as a "technology RYF Talos II mainboard}. This platform is available as a "technology
preview": although it is supported, substitutes are not yet available preview": although it is supported, substitutes are not yet available
from the build farm (@pxref{Substitutes}), and some packages may fail to 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 community is actively working on improving this support, and now is a
great time to try it and get involved! great time to try it and get involved!
@item riscv64-linux @item riscv64-linux
little-endian 64-bit RISC-V processors, specifically RV64GC, and little-endian 64-bit RISC-V processors, specifically RV64GC, and
Linux-Libre kernel. This platform is available as a "technology preview": Linux-Libre kernel. This platform is available as a "technology
although it is supported, substitutes are not yet available from the preview": although it is supported, substitutes are not yet available
build farm (@pxref{Substitutes}), and some packages may fail to build from the build farm (@pxref{Substitutes}), and some packages may fail to
(@pxref{Tracking Bugs and Patches}). That said, the Guix community is build (@pxref{Tracking Bugs and Changes}). That said, the Guix
actively working on improving this support, and now is a great time to community is actively working on improving this support, and now is a
try it and get involved! great time to try it and get involved!
@end table @end table