unofficial mirror of guix-devel@gnu.org 
 help / color / mirror / code / Atom feed
From: blake@reproduciblemedia.com
To: "Maxime Devos" <maximedevos@telenet.be>,
	"Guix-devel" <guix-devel@gnu.org>
Subject: Re: v2: A proposal of a consistent set of clear rules and        guidelines involving snippets, phases and patches.
Date: Fri, 05 Aug 2022 16:59:36 +0000	[thread overview]
Message-ID: <5948e681e5939058f699c0aa8f4f7c52@reproduciblemedia.com> (raw)
In-Reply-To: <98da36a2-d0cc-77da-77bf-6984253131ac@telenet.be>

Hi Maxime,

Adding some basic grammatical corrections below:

August 5, 2022 1:59 PM, "Maxime Devos" <maximedevos@telenet.be> wrote:

> Here's a v2. I've changed the structure to something close to what Julien proposed, it looks a lot
> better now to me!
> 
> The (^) should probably be tested before the final version.
> 
> I don't think the list of 'guiding principles' is worded well, probably needs more work.
> 
> [something I wrote previously]
> 
> Feel free to try to separate the things, but going previous discussions, many tings are important,
> and they appear all to be inseparable.
> Well seems like I was wrong, it splits nicely in three subsections!
>> I’d suggest starting with a patch against that section to address one
>> specific point that you think is the most pressing one. From there we
>> can continue the discussion.
> 
> As written in another response, I don't really have an opinion on what's more pressing than
> another. I have written three 'points', but we don't have to discuss them all at once, maybe first
> 20.4.5.2? That one sounds relatively simple to me.--- [start]
> 
> 20.4.5 Snippets, phases and patches.
> 
> Snippets, phases and patches at times serve overlapping purposes. To decide between the three,
> there are a few guiding principles:
> 
> * In principle, Guix only has free software; when the upstream source contains some non-free
> software, it has to be removed such that ‘guix build --source’ returns the "freed" source code
> rather than the unmodified upstream source (see: 28.4.1 Software Freedom).

Technical grammatical correction: the software that Guix "has" is that in the monorepo,
but it "distributes" many packages. Thus:
--8<---------------cut here---------------start------------->8---
* In principle, Guix only distributes free software; when the upstream source contains some
non-free software, it should be removed such that ‘guix build --source’ returns the "freed"
source code rather than the unmodified upstream source (see: 28.4.1 Software Freedom).
--8<---------------cut here---------------end--------------->8---

> * The source of the package needs to correspond to what is actually built (i.e., act as the
> corresponding source), to fulfill our ethical and legal obligations.

The [i.e.] addendum above is redundant, its better worded as:
--8<---------------cut here---------------start------------->8---
* The source of a package must correspond to what is actually built (i.e., there must be
an explicit relation between source code and the result of its build for all builds),
to fulfill our ethical and legal obligations.
--8<---------------cut here---------------end--------------->8---


> * It is convenient for the source derived from an origin to build on any system that the upstream
> package supports.
> * The source needs to actually work, not only on your Guix system but also for other systems; this
> requires some care for substitutions involving store items and other architecture-specific changes.
> 
> * Sometimes, there is more than one way to do it. Let's go for the simplest one. Sometimes, which
> tool is the simplest, is subjective, that's fine too.

I think would be more clearly worded as:
--8<---------------cut here---------------start------------->8---
* When presented with a variety of strategies for defining a package, choose whichever is simplest.
Sometimes this is subjective, which is also fine. What matters is that you prefer techniques that
are common within the community (i.e. patterns that appear throughout gnu/packages/...) and
are thus clearly legible for reviewers.
--8<---------------cut here---------------end--------------->8---


> To make things more concrete and to resolve conflicts between the principles, a few cases have been
> worked out:

To a newcomer (the target audience), the above may lead to confusion as to what wasn't already 
concrete in the above descriptions, or what principles above come into conflict. There is a mild,
latent assumption that they are familiar with the Guix workflow, which should be avoided. Thus I 
suggest:
--8<---------------cut here---------------start------------->8---
For the purpose of clarifying preferred practices and reducing friction in the review process
introduced by subjective variation, a few guidelines have been worked out:
--8<---------------cut here---------------end--------------->8---
> 
> 20.4.5.1 Removing non-free software. Non-free software has to be removed in a snippet; the reason is
> that a patch or phase will not work.

Well, it might work on their machine, but not for community standards. To reduce confusion:
--8<---------------cut here---------------start------------->8---
20.4.5.1 Removing non-free software.
Non-free software should be removed using snippets; when removing non-free software, a patch or phase
will not be accepted.
--8<---------------cut here---------------end--------------->8---

> 
> For a patch, the problem is that a patch removing a non-free file automatically contains the
> non-free file (^), and we do not want anything non-free to appear in Guix even if only in its
> patches.
> 

Is better as:
--8<---------------cut here---------------start------------->8---
For patches, the issue is that a patch that removes a non-free file automatically contains the
non-free file (^), and we do not want any non-free software to be distributed with Guix, even 
if it only appears within the context of a patch.

Concerning phases, the problem is that they do not influence the result of ‘guix build --source’.
--8<---------------cut here---------------end--------------->8---

> 20.4.5.2 Removing bundled libraries.
> 
> Bundled libraries should not be removed with a patch, because then the patch would contain the full
> bundled library, which can be large. They can be removed either in a snippet or a phase, often
> using the procedure 'delete-file-recursively'. There are a few benefits for snippets here:
> 
> When using snippets, the bundled library does not occur in the source returned by ‘guix build
> --source’, so users and reviewers do not have to worry about whether the bundled library contains
> malware, whether it is non-free, if it contains pre-compiled binaries ... There are also less
> licensing concerns: if the bundled libraries are removed, it becomes less likely that the licensing
> conditions apply to people sharing the source returned by ‘guix build --source’, especially if the
> bundled library is not actually used on Guix systems. (*)
> 
> As such, snippets are recommended here.
> 
> (*) This is _not_ a claim that you can simply ignore the licenses of libraries when they are
> unbundled and replaced by Guix packages -- there are less concerns, not none.
> 
> 20.4.5.3 Fixing technical issues (compilation errors, test failures, other bugs ...)
> 
> Usually, a bug fix comes in the form of a patch copied from upstream or another distribution. In
> that case, simply adding the patch to the 'patches' field is the most convenient and usually does
> not cause any problems; there is no need to rewrite it as a snippet or a phase.
> 
> If no ready-made patch already exists, then choosing between a patch or a snippet is a matter of
> convenience. However, there are two things to keep in mind:
> 
> First, when the fix is not Guix-specific, it is strongly desired to upstream the fix to avoid the
> additional maintenance cost to Guix. As upstreams cannot accept a snippet, writing a patch can be a
> more efficient use of time. Secondly, if the fix of a technical issue embeds a store file name,
> then it has to be a phase. Otherwise, if a store file name was embedded in the source, the result
> of 'guix build --source' would be unusable on non-Guix systems and likely also unusable on Guix
> systems of another architecture.

And some basic last corrections here:
--8<---------------cut here---------------start------------->8---
First, when the fix is not Guix-specific, it is strongly desired by upstream that the fix avoids any
additional maintenance costs for Guix. As upstream cannot accept a snippet, writing a patch can be a
more efficient use of time. Secondly, if the fix of a technical issue embeds a store file name,
then it has to be a phase. Otherwise, if the store file name were to be embedded in the source, the
result of 'guix build --source' would be unusable on non-Guix systems, and also likely unusable on
Guix systems of another architecture.
--8<---------------cut here---------------end--------------->8---


  parent reply	other threads:[~2022-08-05 16:59 UTC|newest]

Thread overview: 41+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-07-25  3:17 A proposal of a consistent set of clear rules and guidelines involving snippets, phases and patches Maxime Devos
2022-07-25  5:21 ` Julien Lepiller
2022-07-25 11:18   ` Maxime Devos
2022-07-25 11:37     ` Julien Lepiller
2022-08-04  8:51 ` Ludovic Courtès
2022-08-05  3:23 ` Philip McGrath
2022-08-05  8:13   ` Maxime Devos
2022-08-05  3:38 ` Philip McGrath
2022-08-05  8:09   ` Maxime Devos
2022-08-05 10:18 ` Maxime Devos
2022-08-05 13:59 ` v2: " Maxime Devos
2022-08-06  6:55   ` [PATCH] doc: Update contribution guidelines on patches, etc Liliana Marie Prikler
2022-08-06  6:55     ` [PATCH v2] " Liliana Marie Prikler
2022-09-02 13:12       ` Ludovic Courtès
2022-09-02 18:05         ` Maxime Devos
2022-09-05  9:47           ` Ludovic Courtès
2022-09-05 13:12             ` Maxime Devos
2022-09-05 16:05               ` Maxime Devos
2022-08-09 16:45     ` [PATCH] " Maxime Devos
2022-08-09 17:05       ` Liliana Marie Prikler
2022-08-09 18:19         ` Maxime Devos
2022-08-09 19:08           ` Liliana Marie Prikler
2022-08-09 20:30             ` Maxime Devos
2022-08-10  4:25               ` Liliana Marie Prikler
2022-08-09 20:40             ` Maxime Devos
2022-08-08 21:51   ` v2: A proposal of a consistent set of clear rules and guidelines involving snippets, phases and patches Andreas Enge
2022-08-09 15:06     ` Maxime Devos
2022-08-09 17:10       ` Andreas Enge
2022-09-05 13:03     ` Maxime Devos
2022-09-07 12:17       ` Andreas Enge
2022-09-07 18:08         ` Maxime Devos
2022-08-09 18:58   ` david larsson
2022-08-09 20:53     ` Maxime Devos
2022-08-10 11:23       ` david larsson
2022-08-05 16:59 ` blake [this message]
2022-08-09 16:30   ` Maxime Devos
2022-09-05 14:06     ` Maxime Devos
2022-08-10  6:10   ` blake
2022-08-10  9:06     ` Maxime Devos
2022-08-10 10:33     ` blake
2022-08-10 10:44       ` Maxime Devos

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://guix.gnu.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=5948e681e5939058f699c0aa8f4f7c52@reproduciblemedia.com \
    --to=blake@reproduciblemedia.com \
    --cc=guix-devel@gnu.org \
    --cc=maximedevos@telenet.be \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/guix.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).