Re: v2: A proposal of a consistent set of clear rules and guidelines involving snippets, phases and patches.

[blake]

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---