me
/
guix
Archived
1
0
Fork 0
Code

doc: Make changes to the handling of branches. 

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.

 6. Document how to manage branches without commit access.

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
master
Christopher Baines 2024-05-08 12:29:59 +01:00
parent b462cff5ee
commit 4955589f2f
No known key found for this signature in database
GPG Key ID: 5E28A33B0B84F577
1 changed files with 50 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
doc/contributing.texi
View File

@ -2298,9 +2298,9 @@ indication of its build status on various platforms.
@cindex feature branches, coordination @cindex feature branches, coordination
To help coordinate the merging of branches, you must create a new 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 guix-patches issue each time you create a branch (@pxref{The Issue
Issue Tracker}). The title of the issue requesting to merge a branch Tracker}). The title of the issue requesting to merge a branch should
should have the following format: have the following format:
@cindex merge requests, template @cindex merge requests, template
@example @example
@ -2308,20 +2308,51 @@ Request for merging "@var{name}" branch
@end example @end example
The @url{https://qa.guix.gnu.org/, QA infrastructure} recognizes such The @url{https://qa.guix.gnu.org/, QA infrastructure} recognizes such
issues and lists the merge requests on its main page. Normally branches issues and lists the merge requests on its main page. The following
will be merged in a ``first come, first merged'' manner, tracked through points apply to managing these branches:
the guix-patches issues.
If you agree on a different order with those involved, you can track @enumerate
this by updating which issues block@footnote{You can mark an issue as @item
blocked by another by emailing @email{control@@debbugs.gnu.org} with the The commits on the branch should be a combination of the patches
following line in the body of the email: @code{block XXXXX by YYYYY}. relevant to the branch. Patches not related to the topic of the branch
Where @code{XXXXX} is the number for the blocked issue, and @code{YYYYY} should go elsewhere.
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 @item
the oldest issue, or the issue that isn't @dfn{blocked} by any other Any changes that can be made on the master branch, should be made on the
branch merges. An ordered list of branches with the open issues is master branch. If a commit can be split to apply part of the changes on
available at @url{https://qa.guix.gnu.org}. 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 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 has passed for the build farms to have processed the changes, and for
@ -2329,6 +2360,9 @@ the necessary testing to have happened. For example, you can check
@indicateurl{https://qa.guix.gnu.org/branch/@var{branch}} to see @indicateurl{https://qa.guix.gnu.org/branch/@var{branch}} to see
information on some builds and substitute availability. 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 @node Debbugs User Interfaces
@subsection Debbugs User Interfaces @subsection Debbugs User Interfaces