From patchwork Sat Aug 6 06:55:03 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Liliana Marie Prikler X-Patchwork-Id: 42364 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 BCE6927BBEA; Fri, 9 Sep 2022 16:11:02 +0100 (BST) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-1.7 required=5.0 tests=BAYES_00,DKIM_ADSP_CUSTOM_MED, DKIM_INVALID,DKIM_SIGNED,FREEMAIL_FROM,MAILING_LIST_MULTI, PP_MIME_FAKE_ASCII_TEXT,SPF_HELO_PASS,URIBL_BLOCKED autolearn=no 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 E693227BBE9 for ; Fri, 9 Sep 2022 16:11:01 +0100 (BST) Received: from localhost ([::1]:46704 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oWfen-0007Tg-3I for patchwork@mira.cbaines.net; Fri, 09 Sep 2022 11:11:01 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:35364) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oWfdq-0006dk-TE for guix-patches@gnu.org; Fri, 09 Sep 2022 11:10:02 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:46310) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oWfdq-0002Iy-Jl for guix-patches@gnu.org; Fri, 09 Sep 2022 11:10:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oWfdq-0003Be-BO for guix-patches@gnu.org; Fri, 09 Sep 2022 11:10:02 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#57598] [alternative PATCH] doc: Update contribution guidelines on patches, etc. References: <20220905160048.18173-1-maximedevos@telenet.be> In-Reply-To: <20220905160048.18173-1-maximedevos@telenet.be> Resent-From: Liliana Marie Prikler Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Fri, 09 Sep 2022 15:10:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 57598 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 57598@debbugs.gnu.org Cc: Maxime Devos Received: via spool by 57598-submit@debbugs.gnu.org id=B57598.166273619212231 (code B ref 57598); Fri, 09 Sep 2022 15:10:02 +0000 Received: (at 57598) by debbugs.gnu.org; 9 Sep 2022 15:09:52 +0000 Received: from localhost ([127.0.0.1]:35009 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oWfdf-0003BB-Im for submit@debbugs.gnu.org; Fri, 09 Sep 2022 11:09:52 -0400 Received: from mail-ej1-f65.google.com ([209.85.218.65]:33655) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oWfdd-0003Ay-DI for 57598@debbugs.gnu.org; Fri, 09 Sep 2022 11:09:50 -0400 Received: by mail-ej1-f65.google.com with SMTP id lc7so4789376ejb.0 for <57598@debbugs.gnu.org>; Fri, 09 Sep 2022 08:09:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:message-id:content-transfer-encoding:cc:to:subject :date:from:from:to:cc:subject:date; bh=DSH2NtZY3PQTC9fFJQkWMf/DkB/1uEtpmw/Cv0n+AMo=; b=RB27Z8fDTtIJ2XFhBirBQANWfULF0jfkBugGZd4Rw0w6xoRT4pHsnPzA/oUwy+QU4c 2kl9ebzqGuLU31Dxvb3pYQyJilPkTfwNIlxb8T5Ae0DDDFUJ/3OFjLg1ORSnlBsNFYeh ab1QRNL7dsEruUKgQElSScUflGRqFadVfFUXY/zNOEAwE6PuP2P8QRYrPsKlUAaJuGzI DpqRrZ7H7yJUp2vkY4iuUiqW6gVEXnSyOtwbkJCIKDRmB7Xa7QsTalWn/pqmoTBGfJUF tZ6/bPbrlTbMScxnr7FUdnP4Dz7kx5uRZSr9l/QWm7pIuwnwESrv50ygtNQgYNG0dfm1 pILQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=mime-version:message-id:content-transfer-encoding:cc:to:subject :date:from:x-gm-message-state:from:to:cc:subject:date; bh=DSH2NtZY3PQTC9fFJQkWMf/DkB/1uEtpmw/Cv0n+AMo=; b=GjYi+GizlJchSsS5oFpLLPwS97G55b+1jnU1J3wI1q8liMrm1xfylMx0zEThGzQ0au hsBjyJAgm5IBVlbfZXd+F5N7n2DSdNbv9OTUlG6CPEYEKtxk9wrxoQ91RNa2xEK0a9ZP yxYv1sgGFt7ibI/jYgYo+e475hOVile106DKh/qZxy6M9mDIo4NuiSxgGPy+KE1AkeuX OofFU2WSyfjTkn9qggVWn5BvcUt6xTpg6RQQE3xmfkhth6ONndQWbIZcgEOAb1Z35Fik icuAn0tZBEvCNsOBLGlZnNDDfN8rRSZAS8NxZxyRul6Pa1v1b4vDnVCEZCROe4SAMQTK 93iw== X-Gm-Message-State: ACgBeo1H2SPRi20lgo7GbcB57M8vAcIwahZa3dizEXvYeX2b8+f7xiGV HGhz7nPsg2FKQQyrqk9WIS7hKCrqt+A= X-Google-Smtp-Source: AA6agR5rA2mTbgIBetX28G58h2IWMDUL2Bom3iKU1G5I9NNBL3Cc5B7j6p74jt+jiXD6+YpXV6jpqA== X-Received: by 2002:a17:907:2c75:b0:741:5871:4318 with SMTP id ib21-20020a1709072c7500b0074158714318mr9954710ejc.532.1662736183642; Fri, 09 Sep 2022 08:09:43 -0700 (PDT) Received: from nijino.fritz.box (85-127-52-93.dsl.dynamic.surfer.at. [85.127.52.93]) by smtp.gmail.com with ESMTPSA id kz5-20020a17090777c500b007708851c6f0sm389200ejc.146.2022.09.09.08.09.43 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 09 Sep 2022 08:09:43 -0700 (PDT) From: Liliana Marie Prikler Date: Sat, 6 Aug 2022 08:55:03 +0200 Message-ID: <246b28ff9c402cfce8c2ef799d7d73b1dbb2cca9.camel@gmail.com> 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" X-getmail-retrieved-from-mailbox: Patches * doc/contributing.texi ("Snippets versus Phases"): Replaced with... ("Modifying Sources"): ... this. List more use cases and some principles. --- Hi Maxime, here is an update of my guidelines patch, incorporating the changes Ludo’ requested and some of your bits, as well as fixing some omissions. Cheers doc/contributing.texi | 115 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 102 insertions(+), 13 deletions(-) diff --git a/doc/contributing.texi b/doc/contributing.texi index 17a54f94cc..4894982259 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -451,7 +451,7 @@ needed is to review and apply the patch. * Package Naming:: What's in a name? * Version Numbers:: When the name is not enough. * Synopses and Descriptions:: Helping users find the right package. -* Snippets versus Phases:: Whether to use a snippet, or a build phase. +* Modifying Sources:: When to use patches, snippets, or build phases. * Emacs Packages:: Your Elisp fix. * Python Modules:: A touch of British comedy. * Perl Modules:: Little pearls. @@ -708,20 +708,109 @@ Gettext}): for the X11 resize-and-rotate (RandR) extension. @dots{}") @end lisp -@node Snippets versus Phases -@subsection Snippets versus Phases +@node Modifying Sources +@subsection Modifying Sources +@cindex patches, when to use @cindex snippets, when to use -The boundary between using an origin snippet versus a build phase to -modify the sources of a package can be elusive. Origin snippets are -typically used to remove unwanted files such as bundled libraries, -nonfree sources, or to apply simple substitutions. The source derived -from an origin should produce a source that can be used to build the -package on any system that the upstream package supports (i.e., act as -the corresponding source). In particular, origin snippets must not -embed store items in the sources; such patching should rather be done -using build phases. Refer to the @code{origin} record documentation for -more information (@pxref{origin Reference}). + +Guix has three main ways of modifying the source code of a package, +that you as a packager may use. Each one has its strengths and +drawbacks, along with intended and historically derived use cases. +These are + +@table @b + +@item patches +If your package has a bug that takes multiple lines to fix, or a fix +has already been accepted upstream, patches are the preferred way of +eliminating said bug.@footnote{If you patch a bug that has hitherto +not been reported or fixed upstream, consider also contacting upstream +unless the bug and its fix are specific to Guix.} +Refer to the @code{origin} record documentation +(particularly the fields @code{patches}, @code{patch-inputs}, and +@code{patch-flags}) for more information on how to use patches +(@pxref{origin Reference}). +When adding a patch, do not forget to also list it in +@code{dist_patch_DATA} of @file{gnu/local.mk} + +As patches are applied to the origin of a package, they become part +of the corresponding source. You can retrieve this source by +invoking @code{guix build -S YOUR_PACKAGE}. This also means that +modifying the patch causes two rebuilds: one for the source and one +for the package built from it. + +Patches are limited in that they lack the expressiveness of Guile. +If all changes are constrained to single lines, a patch might be much +larger than the equivalent @code{substitute*}. It is further bad form +to use a single patch to address multiple unrelated issues, whereas +snippets can take ``multiple jobs''. + +@item snippets +If your package contains non-free sources, these need to be removed +through a snippet. This snippet should not only remove the sources in +question, but also references to the removed sources in build scripts, +documentation, and so on. @ref{Software Freedom} + +If your package bundles external libraries, snippets are the preferred +way of removing said them. Unlike with non-free sources, it is not a +requirement to remove @emph{all} bundled libraries, although doing so +is very much preferred. Bundled libraries that are kept should be +clearly indicated, preferrably with a reason as to why the bundled copy +remains. As with non-free sources, references to the removed libraries +should also be updated in the snippet. + +Refer to the @code{origin} record documentation +(particularly the fields @code{snippet} and @code{modules}), for more +information on how to use snippets (@pxref{origin Reference}). + +While snippets have all of Guile's core as well as extra @code{modules} +available, their most useful procedure for @emph{editing} sources +(rather than removing them), is @code{substitute*}, which can not deal +with multi-line changes that well. Like patches, snippets become part +of the corresponding source. + +@item build phases +For modifications that retain the intended functionality of the +package, build phases (usually between @code{unpack} and +@code{configure}, sometimes between @code{configure} and @code{build}) +can be used. @ref{Build Phases}. +Such changes include, but are not limited to, fixes of the +build script(s) or embeddings of store paths (e.g. replacement of +@file{/bin/sh} with @code{(search-input-file inputs "bin/sh")}). + +If you need to embed a store path, do so only inside a build phase. +A workaround for patches that span multiple lines, is to use a variable +such as @code{@@store_path@@} inside the patch and substitute the actual +store path at build time via @code{substitute*}. + +Unlike patches and snippets, build phases do @b{not} become part of +the corresponding source of a package, and should thus be avoided for +changes that result in observably different runtime behaviour. +On the other hand, the reduced overhead of unpacking, repacking and +unpacking again might make for a slightly more pleasant debugging +experience. + +@end table + +If your change does not neatly fit in any of the categories above, it +is usually a matter of preference or convenience. + +@cindex auxiliary files + +Sometimes, you may need to add a new file, e.g. a source file or +configuration file, to your package. As a matter of principle +@b{auxiliary files} should be preferred over an equivalent +@code{display} or @code{format} when creating non-trivial files, as that +makes them easier to edit. The exact threshold for a non-trivial file +might be subjective, though it should lie somewhere between +10--20 lines. + +Auxiliary files are stored in the @file{gnu/packages/aux-files} +directory and can be retrieved in a snippet or build phase via +@code{search-auxiliary-file}. +When adding an auxiliary file, do not forget to also list it in +@code{AUX_FILES} of @file{Makefile.am}. @node Emacs Packages @subsection Emacs Packages