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

[Maxime Devos]

Context: it's currently a mess:, and at times contradictory

• There is policy involving those three, as can be seen from the shepherd mess.
• This policy is partially secret, as can be seen by some people treating some things as policy even if it's not in the manual.
  
• Some versions of the policy are based on archeology, e.g. see the 'snippets were introduced for this particular purpose, so don't use it for other things’ which is not documented in the manual as sole legitimate reason and asking contributors to read all past discussions seems too much for me.
• Sometimes, people refer to the manual (Snippets versus Phases) for how things (should) work, but what they say is not actually present in that section of the manual.
  
• Some variants of the policy are contradictory with each other (IIRC)
• Some of the policies are contradictory with current practice in other Guix packages.
  
• '(guix)Snippets versus Phases says Phases' states that it is elusive.
• The section name implies it's a ‘X versus Y’, which seems polarizing? (Maybe?)
  
• The section neglects the is/ought-distinction -- it just says what is typically used for what, not whether they should be used for them and whether they are allowed to be used for other things, so that section does not seem policy to me (except for the single 'should produce' and 'must not' line), only matters of fact.
  

I can't work with such a mess. As such, I've a proposal for a consistent, clear and non-elusive set of rules and guidelines, based on the following principles:

• It appears we cannot agree on what exactly the policy should be, but having a single policy everyone can use even if some would rather have the specifics be a tiny bit different, is much better than the mess of everyone having their own policy.
• There are no absolutes, except that the result of "guix build --source" must be free software;
• There can be more than one (acceptable) way to do things, but this doesn't make things elusive, this just means there are multiple acceptable options and you should probably go for the simplest.
  

More concretely, I propose the following new contents for (guix)Snippets versus Phases (the phrasing could use some work for smooth reading), which I believe to be sufficiently clear (except for some phrasing that could be tweaked, e.g. the phrases are currently rather long), covers a sufficient amount of cases (feel free to respond if you see a missing case), free of contradictions (likewise) and mostly in line with current practice:

[start]

@c: There is no opposition or such, so no versus, let's not start with polarisation.

20.4.5 Snippets, phases and patches

Snippets, phases and patches at times serve overlapping purposes. To decide between the three, there are several considerations to keep in mind:

• Patches must not be used to remove non-free files, because a patch by construction contains the non-free file itself so the patch would be non-free, which would not be acceptable to Guix. Likewise, patches should not be used to remove bundled libraries, to avoid large space usage, but this is not an absolute rule unlike as for non-free files.
  
• Snippets are often convenient for removing unwanted files such as bundled libraries, non-free sources and binaries. It is technically also possible to use phases for this, albeit slightly less convenient at times. However, phases must not be used to remove non-free sources, as then the output of "guix build --source" would still contain the non-free sources, which is incompatible with Guix' stance on free software. Likewise, phases should not be used to remove binaries; however, this is not strictly forbidden.
  
• Snippets must not embed store items in the source, as this is incompatible with cross-compilation and prevents effectively sharing the source code produced with "guix build --source" with people using non-Guix systems.
• In principle, you can apply a patch from a phase. However, this causes the result of "guix build --source" to not correspond to the actual source code anymore (i.e., it doesn't act as corresponding source anymore), so consider this a last resort for situations such as avoiding causing a world-rebuild for a patch fixing a target-specific bug by making the patching conditional upon target-foo?. If you apply a patch from a phase, make sure that the patch appears in the inputs or native-inputs, such that "guix build --source=all" will include the patch.
  
  @c this relaxes the old rule a little
  

• Ideally, the source derived from the origin should be usable for building on any system that the upstream package supports (even if Guix does not support that system), as a courtesy to the people that the source code is shared with. However, this is not an absolute rule, most important is that it is usable on Guix and it is allowed to neglect this recommendation when it is tricky to follow or a large amount of work. For example, if some Windows-specific source files are non-free, you can simply remove them without replacing them by a free implementation, even if that would reduce the set of systems the package can be built on.

Sometimes, there remains more than one acceptable way to accomplish the goal. In that case, choose whatever appears to be most convenient.

[end]

(Comments welcome, and required to go forward)

Greetings,
Maxime

OpenPGP_0x49E3EE22191725EE.asc
Description: OpenPGP public key

OpenPGP_signature
Description: OpenPGP digital signature