From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id wHenG3Ph82LDEgEAbAwnHQ (envelope-from ) for ; Wed, 10 Aug 2022 18:48:51 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id gKGGG3Ph82ISWQAAauVa8A (envelope-from ) for ; Wed, 10 Aug 2022 18:48:51 +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 114E93CA18 for ; Wed, 10 Aug 2022 18:48:51 +0200 (CEST) Received: from localhost ([::1]:49380 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oLot0-00073H-5U for larch@yhetil.org; Wed, 10 Aug 2022 12:48:50 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:48092) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oLosW-000730-MS for guix-devel@gnu.org; Wed, 10 Aug 2022 12:48:22 -0400 Received: from mail-ed1-x542.google.com ([2a00:1450:4864:20::542]:35541) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oLosU-00064L-O5; Wed, 10 Aug 2022 12:48:20 -0400 Received: by mail-ed1-x542.google.com with SMTP id w3so19900878edc.2; Wed, 10 Aug 2022 09:48:17 -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 :in-reply-to:date:from:from:to:cc; bh=U0JhVsu3fPvitsGFF0iH4iCcm8WdrQggca7ge4XI6Kw=; b=h8YLONPHHqkGtwxWSEca7VdSo1aCIbCbsc+Y9hKghar8x3qKk5OHaWISG/e/tE57G2 lt+PdflWKqqJhXeU+0yfJVtovY1ySWh8DAxJJ3/Hrdbp2VZTCV7j176Lb+u+uqbnW59t 2YYKf1raGZ12eGzRFW5+lWs9M/uh6OHqB4ETOKzCoDGB+okxF64jZf8E6vw7Z1A2wKw1 Iqj3Lyumk4RTgmx0/XN71ZVE1uqgW9aB3V2q0KfVw9lXE2AS7BLtZ5rwWLBw+ohKyKMn VN/yuEQCql3Ffy+8U8QKfWPBssQAZDpFAsDK91WHhNV5H2aRAyZrp56zJufESy5RLgAm Z9MQ== 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 :in-reply-to:date:from:x-gm-message-state:from:to:cc; bh=U0JhVsu3fPvitsGFF0iH4iCcm8WdrQggca7ge4XI6Kw=; b=tplTzSdl47/V7WP+tw+DBDg6rsWA32lfvZbkGFNNELMX/6BgjnosLyrw2mxeUllE+Z NUGxBqotQqHWTXPrcE9cO12DqX/iH5l/BRC9oYMllyXSzbweg++/tzvEi+N+GXH+DPnm WafB32yjDrU51brTDiO4qqMrw6E0TeZ1YbvkOtjgvoKj4BlMqfG6c0uQRVfyP7mjGa/t tkyCLz4ZcitpfS8yjHctw3QZ0VziHNzbXCg08bcH9A+X+4llO4OGbZ53Lll56p9o/3XO L+rEXsG1NnfGPdT1GYQpjCeIB0dqew2IDO93FBzOe6P6fekw3CLhcumQ+AZuPenUN5z0 5LLA== X-Gm-Message-State: ACgBeo2zRhdfPXosIgPE+f5tudr3eLXmZt3w9ALaUaHpPiH05tOxYqcl jTigN9ctOdoqigmjy525Gr0= X-Google-Smtp-Source: AA6agR70HbaZbTnkkXlDajaXWHS7qlvZYiKCe4jqbRfXM4HpEcbvITqEMYIt5+4bjq3GFCtSTMKrcw== X-Received: by 2002:aa7:de18:0:b0:43d:30e2:d22b with SMTP id h24-20020aa7de18000000b0043d30e2d22bmr27592845edv.224.1660150096156; Wed, 10 Aug 2022 09:48:16 -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 g14-20020a170906538e00b0072fd1e563e2sm2488399ejo.177.2022.08.10.09.48.15 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 10 Aug 2022 09:48:15 -0700 (PDT) From: Liliana Marie Prikler Date: Sat, 6 Aug 2022 08:55:03 +0200 In-Reply-To: <2fe4881ad87876ae70ef4f3340b34d589a65bb71.camel@gmail.com> Subject: [PATCH v2] doc: Update contribution guidelines on patches, etc. 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: <1dcca575580624ddcc208883ee62d8c75f908139.camel@gmail.com> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::542; envelope-from=liliana.prikler@gmail.com; helo=mail-ed1-x542.google.com X-Spam_score_int: 13 X-Spam_score: 1.3 X-Spam_bar: + X-Spam_report: (1.3 / 5.0 requ) BAYES_00=-1.9, DATE_IN_PAST_96_XX=3.405, 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=no 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=1660150131; 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=U0JhVsu3fPvitsGFF0iH4iCcm8WdrQggca7ge4XI6Kw=; b=Ol10D5A3SqYOCELhoUL7txbZok5oR+IALVQUbsLkh/CUIouQuBKm4ZckiRxod1n7tuBC8w ZFb9mgtHaOh7NaiyB7oWM2L6qkpEzSTXK4YJTnOW1xj99+J+V3fqGv7cljFv2mHEg8go6M EpLXPrxyF8VaUIUutyeVn4Dsu4vjZu/2dTykqXb4pTSfLpvsaMILuQuieddgW0RMn4FBIq /NXNJTB+mEn8finjezREcsUjX8aZM4zGncMeiV7z7hanK87VhxQbDjN16sSnk5k1KlewpN /JfKtoHV9Q1g/bqYPk/vxrdAXiQFOJe1WgE64sy7WrvAuZRFWFiFPxeFcrG/8A== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1660150131; a=rsa-sha256; cv=none; b=MnayGcG5WFccVIHBd4vkKcWjlP98T7yvpT/QNOUpftMwiyGJQ9b94TW6/H3mT5msmCqIbU AU5YrpQma+Yvv1agFyRU/6dHAzG8+w/57NcsM9GsGifgTWKrWGBXb4KtVSyjMahJ/R/+KM fq2fVZLl7yqmsCUKpp62I0H5eqJTru0NVWu05/f/wcIk9cv7xUminLILd+JHx+AUN6r/fy XhgwhwBs21ZQ7+wWK1lrhFe+WLGXbQjwoDriHlT74wKdazRx/KscE61p0Y3tyzI0sej7Eh IAyE1PpUWwlOgI2HfGTaxl9gh2SGXgfexYggTL6L6ocmGPUeCv2jDQrQew7Ovg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=h8YLONPH; 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: -2.49 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=h8YLONPH; 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: 114E93CA18 X-Spam-Score: -2.49 X-Migadu-Scanner: scn0.migadu.com X-TUID: dY1FTOJmp2N3 * doc/contributing.texi ("Snippets versus Phases"): Replaced with... ("Modifying Sources"): ... this. List more use cases and some principles. --- doc/contributing.texi | 108 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 95 insertions(+), 13 deletions(-) diff --git a/doc/contributing.texi b/doc/contributing.texi index 02c7c5ae59..af97d37f34 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,102 @@ 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. 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. 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. + +As part of a build phase, you may further want to use +@b{auxiliary files}, for instance to add new source files. As a matter +of principle, auxiliary files ought to 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 -- 2.37.0