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
parent
3bea4c0c19
commit
0ea096ae23
2 changed files with 80 additions and 78 deletions
|
|
@ -26,7 +26,7 @@ choice.
|
|||
* 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 @@ readability of patches. Seasoned Guix developers may also want to look
|
|||
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 @@ and which optional dependencies should be used. In particular, avoid adding
|
|||
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 @@ $ guix shell -D guix
|
|||
[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,55 @@ email to @email{bug-guix@@gnu.org}, while patch submissions are filed
|
|||
against the @code{guix-patches} package by sending email to
|
||||
@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 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}). 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
|
||||
@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
|
||||
@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.,
|
||||
|
|
|
|||
|
|
@ -637,18 +637,18 @@ includes POWER9 systems such as the
|
|||
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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue