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

[Maxime Devos <maximedevos@telenet.be>]

[-- Attachment #1.1.1.1: Type: text/plain, Size: 5177 bytes --]

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).
  * 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.
  * 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.

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

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.

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.

For a phase, the problem is that phases do not influence the result of 
‘guix build --source’.

(^) It has been noted that git patches support removing files without 
including the file in the patch in <insert link to Philip McGrath's 
e-mail>. If it is verified that the 'patch' utility supports such 
patches, this method can be used and this policy adjusted appropriately.

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.


[-- Attachment #1.1.1.2: Type: text/html, Size: 6186 bytes --]

[-- Attachment #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 929 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 236 bytes --]