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

[Ludovic Courtès]

Hello!

Maxime Devos <maximedevos@telenet.be> skribis:

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

As a rule of thumb, I’d suggest avoiding denigrating wording like this,
in an effort to keep communication smooth and effective.

>  * There is policy involving those three, as can be seen from the
>    shepherd mess.

What is “the shepherd mess”?  Realize also that not everyone may agree
that there is “a mess” in the first place.

The ‘shepherd’ package uses a snippet to fix a bug.  I think that’s akin
to applying a patch: the intent is that ‘guix build -S’ gives you the
code that’s actually built, with patches applied.

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

There’s no secret, but there might be unwritten rules.

I think what we need to do is improve the “Snippets” section of the
manual, as you propose, so we don’t have unwritten rules and
misunderstandings based on hearsay.

[...]

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

I kinda agree with what Julien wrote.

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.

WDYT?

Thanks,
Ludo’.