From patchwork Sat Feb 1 11:43:26 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: 45mg <45mg.writes@gmail.com> X-Patchwork-Id: 38140 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 2004927BBEA; Sat, 1 Feb 2025 11:46:26 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-6.6 required=5.0 tests=BAYES_00,DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED,DKIM_VALID,FREEMAIL_FROM,MAILING_LIST_MULTI, RCVD_IN_DNSWL_BLOCKED,RCVD_IN_VALIDITY_CERTIFIED,RCVD_IN_VALIDITY_RPBL, RCVD_IN_VALIDITY_SAFE,SPF_HELO_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id 3EE0927BBE2 for ; Sat, 1 Feb 2025 11:46:25 +0000 (GMT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1teBwt-0007LS-FX; Sat, 01 Feb 2025 06:46:07 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1teBwq-0007Kh-OW for guix-patches@gnu.org; Sat, 01 Feb 2025 06:46:04 -0500 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1teBwq-0005dn-4O; Sat, 01 Feb 2025 06:46:04 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=MIME-Version:References:In-Reply-To:Date:From:To:Subject; bh=kTLhP7eOxVAyBixFBetnmK4lTMHiffyZRO+XOSa3nEo=; b=H+9njRyIlPwP0JpHYa+rxLdm9PvWDHM6URNIguvnY+wBma8yWJlMchMXaHADAyh5ESMSna0OkCa85J7h1O+AOqys/OaIcFyUzI0c5O7C4ZS1oTMHi67WMET4UN8UOQ4gniernLoLSvDjEqapNcGBvLz2rF7xzatlhmOyh9R9FO6ZNpQbABXLpCOn5/1eVTk2cmR5WBmIc8t3j2NAK4zITcJ1mERsUHrmk0hCBx0SbZNPTbaJ2WW6UVp1/inw2VJ89S2VEjuR2v3fFA21pQIxJGi0Bd35TZCQYU4bcujzBCAKx/APD1Nrt+MDGWH9fV355VcUTJvW7Sbnb1L8COcRJg==; Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1teBwp-00057D-VQ; Sat, 01 Feb 2025 06:46:03 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#75981] [PATCH (WIP) v1.5 4/4] Document 'guix fork'. Resent-From: 45mg <45mg.writes@gmail.com> Original-Sender: "Debbugs-submit" Resent-CC: ludo@gnu.org, maxim.cournoyer@gmail.com, guix-patches@gnu.org Resent-Date: Sat, 01 Feb 2025 11:46:03 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 75981 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 75981@debbugs.gnu.org Cc: Nicolas Graves , Tomas Volf <~@wolfsden.cz>, 45mg <45mg.writes@gmail.com>, Liliana Marie Prikler , Ricardo Wurmus , Attila Lendvai , Ludovic =?utf-8?q?Court=C3=A8s?= , Maxim Cournoyer X-Debbugs-Original-Xcc: Ludovic =?utf-8?q?Court=C3=A8s?= , Maxim Cournoyer Received: via spool by 75981-submit@debbugs.gnu.org id=B75981.173841033619598 (code B ref 75981); Sat, 01 Feb 2025 11:46:03 +0000 Received: (at 75981) by debbugs.gnu.org; 1 Feb 2025 11:45:36 +0000 Received: from localhost ([127.0.0.1]:56721 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1teBwN-000561-MD for submit@debbugs.gnu.org; Sat, 01 Feb 2025 06:45:36 -0500 Received: from mail-pl1-x642.google.com ([2607:f8b0:4864:20::642]:60814) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.84_2) (envelope-from <45mg.writes@gmail.com>) id 1teBwL-00055a-Ch for 75981@debbugs.gnu.org; Sat, 01 Feb 2025 06:45:34 -0500 Received: by mail-pl1-x642.google.com with SMTP id d9443c01a7336-21654fdd5daso50590765ad.1 for <75981@debbugs.gnu.org>; Sat, 01 Feb 2025 03:45:33 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1738410327; x=1739015127; darn=debbugs.gnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=kTLhP7eOxVAyBixFBetnmK4lTMHiffyZRO+XOSa3nEo=; b=CMNPlc3CW9YnyBT1/+HScsq0EDFnNwoDKzOOp9FKDwWj7Pe2hij1ToNAEpuZBeyBaE NYb6Bk4o5phxep0hxZbQJbEWVNjNYIHC8FFpyjoitpL9PVLUB4AiH74kcZ2ZUluQOPM4 iBz56zl8Kvt41FfXVbmucrlBvkLnr3zGLXiaZ1cghDSyIh7vfVw2CRoVsVE4XVrwC4oH jOPLCe//1isx0strjoGgujOSxQNecNxJEg8gcMr84LG3rFM9FR+2VosPdcqbQbW7lsJk eLd4KEJvFuX8omYZ9DEE6E9Zgb9qll2fBNuBLtGJJl91KvbGTIef1Bx5r97YBApqjKC2 JdVw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738410327; x=1739015127; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=kTLhP7eOxVAyBixFBetnmK4lTMHiffyZRO+XOSa3nEo=; b=Vcm/n+PyiMLBdym/dulhh/kDg1YFGO9L+H7+nYucYb/OkKQWF0znnvCf/zXZBTrqsO ZDn5gMzmD/nzs0QGO28WYKKls3Lu72w5GJKLEYCsLF2y9eHxnNAv82tAqgkHTVTpo+9P IjBhk7u3BiC74CWDYQtKTJkX6E3JVVaPr/Nnf0AOUrAIPWT1ZAnmLMXen24ku2Q2X23H uouveadhlPUqT1l9mw2A5hYgsF+derw3Uu5Ik2ZtwpUUWq1pT8Tz0qUnZxHlJS0c/Ery 5G7IBV6TVoi0e6rzKFEiG9U7XpCTFgLurCxeuIUJ+A9KZu4zIrEiiOeKrFKutyLkxvRW sgcw== X-Gm-Message-State: AOJu0Yx8pisBqQKFBawrF6C2QiQ7uQ2vYeElh0hp1FoqL1bfnJyiNWQ3 CS4uEg+2DU14xKBi1o1vs9vIsskKVD/88ifj/7T1vwxt7mG4/26NY/DCP0ce X-Gm-Gg: ASbGncvWtNPFxTr0wDKPRf6iVAJNgzClSAfLOL5tCo+AtfZ+4kUuexw6L4KrFDyualt mw8lPeD4Hy85SpnDaILT+suuUPYCdX2uoKmJyY5apPXto7oY4WMB0XQE7n+srz+o7KrTD3S7S2A FUuHtcI2WSSxj1tRAEF7BFNmuL+7SyE0Q9JsFpX4/1zMFhR7cxMsyO8uqMNiSIGIY4kOM0fLulD Bv2jG9c+sE/3wijIyjEcDT0K9pAJPzLF5T0zonlawIqwlNMHeW1poezfdIg/J81L+Sl5OwZLzjM GOalT5Ry26tL64IQKtC+4v8AemcFBtzOlmg/jg== X-Google-Smtp-Source: AGHT+IF+4YhbDM5krb8XTSjtwu75EH4CwFw9X+d4yRFSwgufUildNACOeZ6Fw1i/MOM/eJ7oJgRgKg== X-Received: by 2002:a17:902:db03:b0:215:b33b:e26d with SMTP id d9443c01a7336-21dd7c5141fmr216797555ad.21.1738410327178; Sat, 01 Feb 2025 03:45:27 -0800 (PST) Received: from localhost.localdomain (utm3.nitt.edu. [14.139.162.2]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-21de331f8d4sm43844805ad.224.2025.02.01.03.45.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 01 Feb 2025 03:45:26 -0800 (PST) From: 45mg <45mg.writes@gmail.com> Date: Sat, 1 Feb 2025 17:13:26 +0530 Message-ID: <49cb491b107b5f0899209905d7679ba389bc65e6.1738408683.git.45mg.writes@gmail.com> X-Mailer: git-send-email 2.48.1 In-Reply-To: References: MIME-Version: 1.0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches * doc/guix.texi (Invoking guix fork): New node. * doc/contributing.texi (Using Your Own Patches): New node. Change-Id: I06240f0fe8d1fe39f27130a72f5d0d92949c99da --- doc/contributing.texi | 50 ++++++++++++++ doc/guix.texi | 150 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 200 insertions(+) diff --git a/doc/contributing.texi b/doc/contributing.texi index c94ae940fa..bd4fd6c2ac 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -35,6 +35,7 @@ Contributing * Making Decisions:: Collectively choosing the way forward. * Commit Access:: Pushing to the official repository. * Reviewing the Work of Others:: Some guidelines for sharing reviews. +* Using Your Own Patches:: Using your own work before it's accepted. * Updating the Guix Package:: Updating the Guix package definition. * Deprecation Policy:: Commitments and tools for deprecation. * Writing Documentation:: Improving documentation in GNU Guix. @@ -3095,6 +3096,55 @@ Reviewing the Work of Others have reviewed more easily by adding a @code{reviewed-looks-good} usertag for the @code{guix} user (@pxref{Debbugs Usertags}). +@node Using Your Own Patches +@section Using Your Own Patches + +If you've taken the time to contribute code to Guix, chances are that +you want the changes you've made to be reflected in your own Guix +installation as soon as possible. Maybe you've added a package you want, +and you want to start using it @emph{right now}. Or you've fixed a bug +that affects you, and you want it to @emph{go away}. + +As described in the preceding sections, all contributions to Guix first +go through a review process to ensure code quality. Sometimes, this can +take longer than one would like. Ideally, the pace of the review process +should not prevent you from benefiting from your own work. + +One way to work around this issue is to create an additional channel of +your own (@pxref{Creating a Channel}), and add your code to it. For +certain kinds of contributions, such as adding a new package, this is +fairly straightforward - simply copy your new package definition(s) into +a new file in the channel, and remove them when your contribution is +accepted. + +However, there may be cases where this is not convenient. Certain kinds +of changes, such as those that need to modify existing Guix internals, +may be more challenging to incorporate into a channel. Moreoever, the +more substantial your contribution is, the more work it will be to do +so. + +@cindex fork, of Guix +For such cases, there is another option. Recall that the patch series +that you sent (@pxref{Sending a Patch Series}) was created from a one or +more commits on a checkout of the Guix repository (@pxref{Building from +Git}). You could simply specify this repository (referred to as your +`Guix fork', or simply `fork', from here onwards), and its relevant +branch, as your `@code{guix}' channel (@pxref{Using a Custom Guix +Channel}). Now `@code{guix pull}' will fetch your new commits, and +you'll see the changes you made reflected in your Guix installation! + +However, there's a potential complication to this approach - the issue +of authentication (@pxref{Channel Authentication}). If your fork only +exists on your local filesystem (a `local fork'), then you probably +don't need to worry about this, and can pull without authentication +(@pxref{Invoking guix pull}). But other situations, such as a remotely +hosted fork, may make it important for your fork to be authenticated, in +the same way that all channels are expected to be. + +Guix provides a @command{guix fork} command in order to simplify and +automate many details of creating and managing and authenticated +fork. For more information, @pxref{Invoking guix fork}. + @node Updating the Guix Package @section Updating the Guix Package diff --git a/doc/guix.texi b/doc/guix.texi index b1b6d98e74..bbb5666d0a 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -311,6 +311,7 @@ Top * Invoking guix pack:: Creating software bundles. * The GCC toolchain:: Working with languages supported by GCC. * Invoking guix git authenticate:: Authenticating Git repositories. +* Invoking guix fork:: Creating and managing authenticated forks of Guix. Programming Interface @@ -5930,6 +5931,7 @@ Development * Invoking guix pack:: Creating software bundles. * The GCC toolchain:: Working with languages supported by GCC. * Invoking guix git authenticate:: Authenticating Git repositories. +* Invoking guix fork:: Creating and managing authenticated forks of Guix. @end menu @node Invoking guix shell @@ -7534,6 +7536,154 @@ Invoking guix git authenticate @end table +@node Invoking guix fork +@section Invoking @command{guix fork} + +@cindex @command{guix fork} + +The @command{guix fork} command provides the means to quickly set up, +authenticate, and keep up-to-date an authenticated fork of Guix. For +more information on authentication of a Guix checkout, @pxref{Invoking +guix git authenticate}. + +Its syntax is: + +guix fork ACTION ARGS... + +ACTION specifies the fork-related action to perform. Currently, the +following values are supported: + +@table @code +@item create SIGNING_KEY [DIRECTORY OPTIONS...] +Create a fork of Guix in DIRECTORY, using SIGNING_KEY to sign the introductory +commit. +DIRECTORY defaults to ./guix. + +First, clone Guix into DIRECTORY, unless @code{--use-existing} is +given. Then, add SIGNING_KEY to the `@code{keyring}' branch of the +repository. Finally, create a new `@code{fork}' branch based starting +from the default branch, whose initial commit authorizes SIGNING_KEY +alone (by adding it to @file{.guix-authorizations}) and is signed by it. + +The new `@code{fork}' branch is intended to mirror upstream +Guix. Updating the fork amounts to applying all new commits to it (see +the `@code{update}' command below for further explanation). You can work +on patches in branches based off of this one, in much the same way as +you would base them on Guix's default branch - every commit from the +latter will be present in the former. + +To @command{guix pull} your changes, you could create a `build' branch +starting from the initial fork commit, onto which you can cherry-pick or +rebase commits from patch branches. This branch can then be specified +for the `@code{guix}' channel (@pxref{Using a Custom Guix Channel}). +Updating this channel can be done by merging the `@code{fork}' branch +into it. + +OPTIONS can be one or more of the following: + +@table @code +@item --use-existing +Use existing clone of Guix in DIRECTORY. This is useful if you've +already created commits for a patch series (@pxref{Using Your Own +Patches}). However, all commits to the default branch, as well as any +branches that may be merged into it in the future, must have been signed +with an authorized key; otherwise, authentication will fail later. +@item --upstream=URI +The repository to clone from. This defaults to the default URL for the +Guix repository. +@item --channel-url=URI +Optional URI, which if given, will be used to replace the channel URL. +Furthermore, the existing `origin' remote (which tracks +`@code{upstream}') is renamed to `upstream', and a new `origin' remote +is created to track URI. +@item --git-parameter PARAMETER +Specify configuration PARAMETER for git, via `-c' option. You can pass +this option multiple times. +@end table + +@cindex authentication, of Guix forks +@item authenticate UPSTREAM COMMIT SIGNER [OPTIONS...] +Authenticate a Guix fork, using COMMIT and SIGNER as the fork +introduction. + +First, authenticate new commits from UPSTREAM, using Guix's default +introduction. Then authenticate the remaining commits using the fork +introduction. + +As with @code{guix git authenticate}, all three of UPSTREAM, COMMIT and +SIGNER will be cached in .git/config, so that you don't need to specify +them after the first time. + +OPTIONS can be one or more of the following: + +@table @code +@item --repository=DIRECTORY +@itemx -r DIRECTORY +Authenticate the git repository in DIRECTORY, instead of the current +directory. +@item --upstream-commit=COMMIT +@itemx --upstream-signer=SIGNER +Use COMMIT/SIGNER as the introduction for upstream +Guix, instead of Guix's default channel introduction. +@item --keyring=REFERENCE +@itemx -k REFERENCE +Load keyring for fork commits from REFERENCE, a Git branch (default +`@code{keyring}'). +@item --upstream-keyring=REFERENCE +Load keyring for upstream commits from REFERENCE, a Git branch (default +`@code{keyring}'). +@item --end=COMMIT +Authenticate fork commits up to COMMIT. +@item --upstream-end=COMMIT +Authenticate upstream commits up to COMMIT. + +@item --cache-key=KEY +@itemx --historical-authorizations=FILE +@itemx --stats +Identical to the correponding options in @command{guix git authenticate} +(@pxref{Invoking guix git authenticate}). +@end table + +@item update [OPTIONS...] +Pull into this Guix fork's configured upstream branch (from running +@command{guix fork authenticate}), then apply new commits onto the +current branch. + +This approach may seem less convenient than simply merging the upstream +branch into the fork branch. Indeed, it duplicates every upstream commit +under a different commit hash, and applying a large number of commits +can be slow. However, this is currently the only feasible approach due +to the nature of Guix's authentication mechanism. Namely, merge commits +can only be authenticated if both their parents are signed by an +authorized key, meaning that you can only use the merge workflow if +you're authorized to commit to upstream Guix. + +For mapping commits on the fork branch to their equivalents on the +upstream branch, you can use @command{guix fork identify} (see below). + +OPTIONS can be one or more of the following: + +@table @code +@item --repository=DIRECTORY +@itemx -r DIRECTORY +Act in the Git repository in DIRECTORY. +@item --fork-branch=BRANCH +Apply new commits onto BRANCH instead of the current branch. +@end table + +@item identify +Coming soon! + +Given a commit hash from upstream Guix, print its equivalent on the fork +branch, or vice versa. +This uses the 'Change-Id:' line added to commit messages by Guix's +'commit-msg' hook. +The first invocation of this command will be slow, as the entire set of +corresponding commits is built up as a hash table, and then +cached. Subsequent invocations should be nearly instant. + +@end table + @c ********************************************************************* @node Programming Interface @chapter Programming Interface