[bug#63459] [PATCH] doc: Rewrite the branching strategy.

[Christopher Baines]

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): Rewrite branching strategy.
---
 doc/contributing.texi | 58 +++++++++++++++++--------------------------
 1 file changed, 23 insertions(+), 35 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 7bf350ee0d..c54910e34d 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1264,41 +1264,29 @@ Submitting Patches
 @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.
+Changes to packages with 300 dependent packages or less can be pushed to
+the @code{master} branch.
+
+Larger changes should be first pushed to a branch other than
+@code{master}. This allows for testing and for the build farms to
+process the changes prior to being pushed to the @code{master} branch.
+
+To help coordinate the merging of branches, you must create a new
+guix-patches issue each time you wish to merge a branch. 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 blocked by the issue previously at the back of the queue.
+
+Normally branches will be merged in a ``first come, first merged''
+manor, tracked through the guix-patches issues. If you agree 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 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.
 
 @item
 @cindex determinism, of build processes

base-commit: 9d05f9a9f538061e1fdc5aedb0748d260fcf20f7
prerequisite-patch-id: ae24e25c683be86ce0b3fa1fde1bd30e3e08e248
-- 
2.39.1