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: 5698 bytes --]

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


[-- Attachment #1.1.1.2: Type: text/html, Size: 6713 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 --]