From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id QBYiBcES7mLbJQEAbAwnHQ (envelope-from ) for ; Sat, 06 Aug 2022 09:05:37 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id 0Ho9BMES7mLSOwAAG6o9tA (envelope-from ) for ; Sat, 06 Aug 2022 09:05:37 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 49E77F722 for ; Sat, 6 Aug 2022 09:05:36 +0200 (CEST) Received: from localhost ([::1]:51514 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oKDsN-0003F1-8e for larch@yhetil.org; Sat, 06 Aug 2022 03:05:35 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:49278) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oKDrO-0003Eb-NZ for guix-devel@gnu.org; Sat, 06 Aug 2022 03:04:34 -0400 Received: from mail-ed1-x544.google.com ([2a00:1450:4864:20::544]:33663) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oKDrM-0006k4-Ts; Sat, 06 Aug 2022 03:04:34 -0400 Received: by mail-ed1-x544.google.com with SMTP id b96so5846086edf.0; Sat, 06 Aug 2022 00:04:31 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:date:subject:in-reply-to:to:cc:content-transfer-encoding :message-id:mime-version; bh=x/HG0G5ibzx51khhR+zL0E9oSfLghS2nP08IKb6X4Zk=; b=GFjSyhes7GDgTwk6Gec48+ifLahgOGmO2LHu4MA7NNJ6ug6La1OGpNUST2VEs5g1hz ScUKdEeLxTi/52Ouw6QoPRf9iX1NXS0eJi3nGb+upYls5XLmovTzGL3byF2G2gcQ5M1z dr6WWA+YsKzlix/i4LwB3h3EdtmYHuRXB4Sv1q3B+tk33fnMzI7sR332iIUCMZpqjNSx 1cYByAndYQiDICsobI4oHPcbIuK5Fp7s7eL9ir7V3zfGfu9Ex4plqNA39ja5aAp2tBI9 fAgGNXmUWQM8Zh0qfVtzWIoUd91b9F1TI+mYf7Ib9DFNCbkGpzM6LupL0gOGP9DBQEqV GIlQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:date:subject:in-reply-to:to:cc :content-transfer-encoding:message-id:mime-version; bh=x/HG0G5ibzx51khhR+zL0E9oSfLghS2nP08IKb6X4Zk=; b=MHYEfZqe2G/s77s/pUeWn6Ru1GPlkuwayLAkkjS/vi+D97N69o4wOtmhq+5pbP0aCm i/3DD6rsr+SKKdxj4nBP2KCnCEz6OpjxDD0BdeKr4yGNPRx+CVX+jic3Wj2o6OL0VdQ3 NVtivRevQWXmnmRkIS03N2guCEEq/W4HPIYWFsdwo+OQvG2Q7nvOiYvIeBUzM9Qv5Iz8 0xh7bqgUJONPYVg7udjLWF44H5xIOz1y/U0SpVSFrNQlVK84bhEqxnU1u9wLKVEadf/p kcFRH4IMxPeEwplATzCwYADxsqHTtkkvwZqx708Ltu5EFjNQagvygLAlpLdBTSlDLR9F f0Pg== X-Gm-Message-State: ACgBeo1oyWceFSiwce29+1Vg6Gs7qlD7Gci/oCk6xp3cRxyWnCuCNoCw x4WYQCPX7FR/DGDL9qgalmc= X-Google-Smtp-Source: AA6agR4WkBJ+A50crttoz3d6WqSOCEMwwuMCRrgerD9Kg2bNu0vTg1RRI8HVH2eFKZW0hU351BGriQ== X-Received: by 2002:a05:6402:d05:b0:425:b7ab:776e with SMTP id eb5-20020a0564020d0500b00425b7ab776emr9993615edb.142.1659769469906; Sat, 06 Aug 2022 00:04:29 -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 x17-20020a170906711100b007304f4107f9sm2392572ejj.52.2022.08.06.00.04.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 06 Aug 2022 00:04:29 -0700 (PDT) From: Liliana Marie Prikler Date: Sat, 6 Aug 2022 08:55:03 +0200 Subject: [PATCH] doc: Update contribution guidelines on patches, etc. In-Reply-To: <98da36a2-d0cc-77da-77bf-6984253131ac@telenet.be> to: Maxime Devos , Guix-devel cc: blake@reproduciblemedia.com, Julien Lepiller , =?ISO-8859-1?Q?Ludovic=5FCourt=E8s?= , Philip McGrath Content-Transfer-Encoding: 7bit Message-ID: <2fe4881ad87876ae70ef4f3340b34d589a65bb71.camel@gmail.com> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::544; envelope-from=liliana.prikler@gmail.com; helo=mail-ed1-x544.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: guix-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: "Guix-devel" X-Migadu-Flow: FLOW_IN X-Migadu-To: larch@yhetil.org X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1659769536; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=x/HG0G5ibzx51khhR+zL0E9oSfLghS2nP08IKb6X4Zk=; b=LnHMNFkisedGmkOfmOqRLxyMFcjMO/sEpkILYivEPyE97XWZm6SH9ihCeqSLTspLqeHU2B JrAmtAQivP9syp83ZC8c5AGYP4gPVILu9ZxTAXYrXW/Qbzsm1VXWd/NxjtLktMBJuOPtOF b6Ddw/qfmIis2vc7F5P2NN860d3ntIA8HTdC9O+CgsbOo8TTi3/+W9wkME8Q2fhDt2A3H8 hMsHKUWbuZ6iqgQ6ZoOOx5FezAJ/+FlJlUyES6t0UOc2mIP7KtufxD71dWl/v8QKfkoxCJ mv7IQO9uhOa390Y1uhsEbFTUwEwtVU3BRI/3/yw8fxQuChfGf2F0pK9ih/+P9w== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1659769536; a=rsa-sha256; cv=none; b=Ks2AEEjNqD8OGfNtAR8Jq1US9evhheqpCTZnbyxHtM648Q2gQojs/FxAzZ2VCKcHCJFRqK oVBYsT96TG7h0p6MEzsGbzG5hJ290jzmBPk5t0fY+hGVa3jCcG8g0X/mAFO+MZj8892/hr yr0FMd1Ktm61yqfKc9i6y4h2LsLXdJa3/fEZCwX971Z9HtaR4IofgBDzvArb4OvB9xh/at iEH+pfyFx9VuKNNMf6UO3PlcQLEtvleCL+aLDDHKLTLVkA1bILo5tqhjN86WJBEUHLePem 66HDSsIScjX2nQXY6ikM+89G4Bn9bTwEwRY4t0EMsJ4DDo11r7Ht5NQ9hSsugw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=GFjSyhes; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -6.19 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=GFjSyhes; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 49E77F722 X-Spam-Score: -6.19 X-Migadu-Scanner: scn0.migadu.com X-TUID: bj07S5Ii7Gh1 * doc/contributing.texi ("Snippets versus Phases"): Replaced with... ("Modifying Sources"): ... this. List more use cases and some principles. --- doc/contributing.texi | 85 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 72 insertions(+), 13 deletions(-) diff --git a/doc/contributing.texi b/doc/contributing.texi index 02c7c5ae59..7a03715abf 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -441,7 +441,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. @@ -698,20 +698,79 @@ 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 @asis + +@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. Refer to the @code{origin} record documentation +(particularly the fields @code{patches}, @code{patch-inputs}, and +@code{patch-flags}) for more information (@pxref{origin Reference}). +When adding a patch, do not forget to also list it in +@code{dist_patch_DATA} of @file{gnu/local.mk} + +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*}. Furthermore, building +a package with an additional patch causes two new derivations to be +built: First the source, then the package. + +@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 (@pxref{origin Reference}). + +Snippets are limited in that @code{substitute*} can not deal with +multi-line changes well. Furthermore, as with patches, modifying the +snippets causes two derivations to be built. + +@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. 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*}. + +Build phases are limited in that they do not modify the source +derivation. Thus, they are inadequate for changes that are to be +reflected in the source code. On the other hand, they only cause a +single rebuild and are thus slightly easier to debug than phases and +snippets. + +@end table + +If your change does not neatly fit in any of the categories above, it +is usually a matter of preference or convenience. @node Emacs Packages @subsection Emacs Packages -- 2.37.0