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

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

[Maxime Devos]

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

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

[Julien Lepiller]

[-- Attachment #1: Type: text/plain, Size: 6676 bytes --]

I don't like the wording at all. You're mixing too many things together.

I think it would be better to first document the guiding principles (eg. the goal that there are no non-free software in Guix, going for the simplest thing, etc) and then derive rules for specific cases, based on these principles:

How do I remove non-free software? -> snippet because …

How do I remove bundled libraries? -> snippet or phase because …

How do I fix a build issue? -> patch or snippet if this affects building from source, can also be a phase if the result of --sources can still build

A test issue?

…

This leaves some cases up to interpretation, but that's probably not so different from "it's not an absolute rule". It's also much clearer and quicker to figure out in which case you are. If not documented as a case, you can fall back to the general principles.

Le 25 juillet 2022 05:17:33 GMT+02:00, Maxime Devos <maximedevos@telenet.be> a écrit :
>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 #2: Type: text/html, Size: 7905 bytes --]

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

[Maxime Devos]

[-- Attachment #1.1.1: Type: text/plain, Size: 1318 bytes --]


On 25-07-2022 07:21, Julien Lepiller wrote:
> I don't like the wording at all. You're mixing too many things together.
Feel free to try to separate the things, but going previous discussions, 
many tings are important, and they appear all to be inseparable.
>
> I think it would be better to first document the guiding principles 
> (eg. the goal that there are no non-free software in Guix, going for 
> the simplest thing, etc) and then derive rules for specific cases, 
> based on these principles:
>
> How do I remove non-free software? -> snippet because …
>
> How do I remove bundled libraries? -> snippet or phase because …
>
> How do I fix a build issue? -> patch or snippet if this affects 
> building from source, can also be a phase if the result of --sources 
> can still build
>
> A test issue?
>
> …
>
> This leaves some cases up to interpretation, but that's probably not 
> so different from "it's not an absolute rule". It's also much clearer 
> and quicker to figure out in which case you are. If not documented as 
> a case, you can fall back to the general principles.

TBC, is the issue here the structure of the section, or some individual 
rules? In the former case, I could try rewriting it a bit to follow your 
proposed structure.

Greetings,
Maxime.

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

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

[Julien Lepiller]

[-- Attachment #1: Type: text/plain, Size: 1627 bytes --]

I agree that we should better document that policy. I think we could go further, but it's ok to document the common denominator first. To me, the structure you suggest is not great, but I don't have issues with the content.

Le 25 juillet 2022 13:18:28 GMT+02:00, Maxime Devos <maximedevos@telenet.be> a écrit :
>
>On 25-07-2022 07:21, Julien Lepiller wrote:
>> I don't like the wording at all. You're mixing too many things together.
>Feel free to try to separate the things, but going previous discussions, many tings are important, and they appear all to be inseparable.
>> 
>> I think it would be better to first document the guiding principles (eg. the goal that there are no non-free software in Guix, going for the simplest thing, etc) and then derive rules for specific cases, based on these principles:
>> 
>> How do I remove non-free software? -> snippet because …
>> 
>> How do I remove bundled libraries? -> snippet or phase because …
>> 
>> How do I fix a build issue? -> patch or snippet if this affects building from source, can also be a phase if the result of --sources can still build
>> 
>> A test issue?
>> 
>> …
>> 
>> This leaves some cases up to interpretation, but that's probably not so different from "it's not an absolute rule". It's also much clearer and quicker to figure out in which case you are. If not documented as a case, you can fall back to the general principles.
>
>TBC, is the issue here the structure of the section, or some individual rules? In the former case, I could try rewriting it a bit to follow your proposed structure.
>
>Greetings,
>Maxime.

[-- Attachment #2: Type: text/html, Size: 2150 bytes --]

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

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

[Philip McGrath]

On Sun, Jul 24, 2022, at 11:17 PM, Maxime Devos wrote:
>  * 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.

It is possible to create patches that do not contain the deleted file, e.g. with `git format-patch --irreversible-delete`. That said, I don't know if the version of `patch` we use to patch origins is able to apply such patches—but maybe it would be a useful feature?

-Philip

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

[Maxime Devos]

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


On 05-08-2022 05:23, Philip McGrath wrote:
> On Sun, Jul 24, 2022, at 11:17 PM, Maxime Devos wrote:
>>   * 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.
> It is possible to create patches that do not contain the deleted file, e.g. with `git format-patch --irreversible-delete`. That said, I don't know if the version of `patch` we use to patch origins is able to apply such patches—but maybe it would be a useful feature?
>
> -Philip

Right, this is possible though it would have to be checked whether it is 
supported, so that statement should be weakened a bit -- to allow 
deleting non-free files with a patch, but noting that you'll have to set 
the right options to avoid including the deleted file in the patch.

I would recommend a (delete-file-recursively ".") over a patch here 
though, to avoid having to remember the --irreversible-delete option and 
in case there is not a git repo.

Greetings,
Maxime.


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

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

[Philip McGrath]

On Sun, Jul 24, 2022, at 11:17 PM, Maxime Devos wrote:
>  * 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.

Should we have an option for "guix build --source=all" to also include the Guix "scripts used to control compilation and installation"?

-Philip

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

[Maxime Devos]

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


On 05-08-2022 05:38, Philip McGrath wrote:
> On Sun, Jul 24, 2022, at 11:17 PM, Maxime Devos wrote:
>>   * 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.
> Should we have an option for "guix build --source=all" to also include the Guix "scripts used to control compilation and installation"?

What do you mean with "Guix scripts" here? I don't think Guix has a 
notion of 'scripts' (except stuff like 'wrap-script', but that doesn't 
seem relevant here). Do you mean the phases code?

Greetings,
Maxime.


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

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

[Maxime Devos]

[-- Attachment #1.1.1: Type: text/plain, Size: 88 bytes --]

Currently writing a v2 with a structure like Julien proposed.

Greetings,
Maxime.


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

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

[Maxime Devos]

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

[PATCH] doc: Update contribution guidelines on patches, etc.

[Liliana Marie Prikler]

* doc/contributing.texi ("Snippets versus Phases"): Replaced with...
("Modifying Sources"): ... this.  List more use cases and some principles.
---
 doc/contributing.texi | 85 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 72 insertions(+), 13 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 02c7c5ae59..7a03715abf 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -441,7 +441,7 @@ needed is to review and apply the patch.
 * Package Naming::              What's in a name?
 * Version Numbers::             When the name is not enough.
 * Synopses and Descriptions::   Helping users find the right package.
-* Snippets versus Phases::      Whether to use a snippet, or a build phase.
+* Modifying Sources::           When to use patches, snippets, or build phases.
 * Emacs Packages::              Your Elisp fix.
 * Python Modules::              A touch of British comedy.
 * Perl Modules::                Little pearls.
@@ -698,20 +698,79 @@ Gettext}):
 for the X11 resize-and-rotate (RandR) extension. @dots{}")
 @end lisp
 
-@node Snippets versus Phases
-@subsection Snippets versus Phases
+@node Modifying Sources
+@subsection Modifying Sources
 
+@cindex patches, when to use
 @cindex snippets, when to use
-The boundary between using an origin snippet versus a build phase to
-modify the sources of a package can be elusive.  Origin snippets are
-typically used to remove unwanted files such as bundled libraries,
-nonfree sources, or to apply simple substitutions.  The source derived
-from an origin should produce a source that can be used to build the
-package on any system that the upstream package supports (i.e., act as
-the corresponding source).  In particular, origin snippets must not
-embed store items in the sources; such patching should rather be done
-using build phases.  Refer to the @code{origin} record documentation for
-more information (@pxref{origin Reference}).
+
+Guix has three main ways of modifying the source code of a package,
+that you as a packager may use.  Each one has its strengths and
+drawbacks, along with intended and historically derived use cases.
+These are
+
+@table @asis
+
+@item patches
+If your package has a bug that takes multiple lines to fix, or a fix
+has already been accepted upstream, patches are the preferred way of
+eliminating said bug.  Refer to the @code{origin} record documentation
+(particularly the fields @code{patches}, @code{patch-inputs}, and
+@code{patch-flags}) for more information (@pxref{origin Reference}).
+When adding a patch, do not forget to also list it in
+@code{dist_patch_DATA} of @file{gnu/local.mk}
+
+Patches are limited in that they lack the expressiveness of Guile.
+If all changes are constrained to single lines, a patch might be much
+larger than the equivalent @code{substitute*}.  Furthermore, building
+a package with an additional patch causes two new derivations to be
+built: First the source, then the package.
+
+@item snippets
+If your package contains non-free sources, these need to be removed
+through a snippet.  This snippet should not only remove the sources in
+question, but also references to the removed sources in build scripts,
+documentation, and so on. @ref{Software Freedom}
+
+If your package bundles external libraries, snippets are the preferred
+way of removing said them.  Unlike with non-free sources, it is not a
+requirement to remove @emph{all} bundled libraries, although doing so
+is very much preferred.  Bundled libraries that are kept should be
+clearly indicated, preferrably with a reason as to why the bundled copy
+remains.  As with non-free sources, references to the removed libraries
+should also be updated in the snippet.
+
+Refer to the @code{origin} record documentation
+(particularly the fields @code{snippet} and @code{modules}), for more
+information (@pxref{origin Reference}).
+
+Snippets are limited in that @code{substitute*} can not deal with
+multi-line changes well.  Furthermore, as with patches, modifying the
+snippets causes two derivations to be built.
+
+@item build phases
+For modifications that retain the intended functionality of the
+package, build phases (usually between @code{unpack} and
+@code{configure}, sometimes between @code{configure} and @code{build})
+can be used.  Such changes include, but are not limited to fixes of the
+build script(s) or embeddings of store paths (e.g. replacement of
+@file{/bin/sh} with @code{(search-input-file inputs "bin/sh")}).
+
+If you need to embed a store path, do so only inside a build phase.
+A workaround for patches that span multiple lines, is to use a variable
+such as @code{@@store_path@@} inside the patch and substitute the actual
+store path at build time via @code{substitute*}.
+
+Build phases are limited in that they do not modify the source
+derivation.  Thus, they are inadequate for changes that are to be
+reflected in the source code.  On the other hand, they only cause a
+single rebuild and are thus slightly easier to debug than phases and
+snippets.
+
+@end table
+
+If your change does not neatly fit in any of the categories above, it
+is usually a matter of preference or convenience.
 
 @node Emacs Packages
 @subsection Emacs Packages
-- 
2.37.0

[PATCH v2] doc: Update contribution guidelines on patches, etc.

[Liliana Marie Prikler]

* doc/contributing.texi ("Snippets versus Phases"): Replaced with...
("Modifying Sources"): ... this.  List more use cases and some principles.
---
 doc/contributing.texi | 108 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 95 insertions(+), 13 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 02c7c5ae59..af97d37f34 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -441,7 +441,7 @@ needed is to review and apply the patch.
 * Package Naming::              What's in a name?
 * Version Numbers::             When the name is not enough.
 * Synopses and Descriptions::   Helping users find the right package.
-* Snippets versus Phases::      Whether to use a snippet, or a build phase.
+* Modifying Sources::           When to use patches, snippets, or build phases.
 * Emacs Packages::              Your Elisp fix.
 * Python Modules::              A touch of British comedy.
 * Perl Modules::                Little pearls.
@@ -698,20 +698,102 @@ Gettext}):
 for the X11 resize-and-rotate (RandR) extension. @dots{}")
 @end lisp
 
-@node Snippets versus Phases
-@subsection Snippets versus Phases
+@node Modifying Sources
+@subsection Modifying Sources
 
+@cindex patches, when to use
 @cindex snippets, when to use
-The boundary between using an origin snippet versus a build phase to
-modify the sources of a package can be elusive.  Origin snippets are
-typically used to remove unwanted files such as bundled libraries,
-nonfree sources, or to apply simple substitutions.  The source derived
-from an origin should produce a source that can be used to build the
-package on any system that the upstream package supports (i.e., act as
-the corresponding source).  In particular, origin snippets must not
-embed store items in the sources; such patching should rather be done
-using build phases.  Refer to the @code{origin} record documentation for
-more information (@pxref{origin Reference}).
+
+Guix has three main ways of modifying the source code of a package,
+that you as a packager may use.  Each one has its strengths and
+drawbacks, along with intended and historically derived use cases.
+These are
+
+@table @b
+
+@item patches
+If your package has a bug that takes multiple lines to fix, or a fix
+has already been accepted upstream, patches are the preferred way of
+eliminating said bug.  Refer to the @code{origin} record documentation
+(particularly the fields @code{patches}, @code{patch-inputs}, and
+@code{patch-flags}) for more information on how to use patches
+(@pxref{origin Reference}).
+When adding a patch, do not forget to also list it in
+@code{dist_patch_DATA} of @file{gnu/local.mk}
+
+As patches are applied to the origin of a package, they become part
+of the corresponding source.  You can retrieve this source by
+invoking @code{guix build -S YOUR_PACKAGE}.  This also means that
+modifying the patch causes two rebuilds: one for the source and one
+for the package built from it.
+
+Patches are limited in that they lack the expressiveness of Guile.
+If all changes are constrained to single lines, a patch might be much
+larger than the equivalent @code{substitute*}.  It is further bad form
+to use a single patch to address multiple unrelated issues, whereas
+snippets can take ``multiple jobs''.
+
+@item snippets
+If your package contains non-free sources, these need to be removed
+through a snippet.  This snippet should not only remove the sources in
+question, but also references to the removed sources in build scripts,
+documentation, and so on. @ref{Software Freedom}
+
+If your package bundles external libraries, snippets are the preferred
+way of removing said them.  Unlike with non-free sources, it is not a
+requirement to remove @emph{all} bundled libraries, although doing so
+is very much preferred.  Bundled libraries that are kept should be
+clearly indicated, preferrably with a reason as to why the bundled copy
+remains.  As with non-free sources, references to the removed libraries
+should also be updated in the snippet.
+
+Refer to the @code{origin} record documentation
+(particularly the fields @code{snippet} and @code{modules}), for more
+information on how to use snippets (@pxref{origin Reference}).
+
+While snippets have all of Guile's core as well as extra @code{modules}
+available, their most useful procedure for @emph{editing} sources
+(rather than removing them), is @code{substitute*}, which can not deal
+with multi-line changes that well.  Like patches, snippets become part
+of the corresponding source.
+
+@item build phases
+For modifications that retain the intended functionality of the
+package, build phases (usually between @code{unpack} and
+@code{configure}, sometimes between @code{configure} and @code{build})
+can be used.  Such changes include, but are not limited to, fixes of the
+build script(s) or embeddings of store paths (e.g. replacement of
+@file{/bin/sh} with @code{(search-input-file inputs "bin/sh")}).
+
+If you need to embed a store path, do so only inside a build phase.
+A workaround for patches that span multiple lines, is to use a variable
+such as @code{@@store_path@@} inside the patch and substitute the actual
+store path at build time via @code{substitute*}.
+
+Unlike patches and snippets, build phases do @b{not} become part of
+the corresponding source of a package, and should thus be avoided for
+changes that result in observably different runtime behaviour.
+On the other hand, the reduced overhead of unpacking, repacking and
+unpacking again might make for a slightly more pleasant debugging
+experience.
+
+@end table
+
+If your change does not neatly fit in any of the categories above, it
+is usually a matter of preference or convenience.
+
+As part of a build phase, you may further want to use
+@b{auxiliary files}, for instance to add new source files.  As a matter
+of principle, auxiliary files ought to be preferred over an equivalent
+@code{display} or @code{format} when creating non-trivial files, as that
+makes them easier to edit.  The exact threshold for a non-trivial file
+might be subjective, though it should lie somewhere between 10~20 lines.
+
+Auxiliary files are stored in the @file{gnu/packages/aux-files}
+directory and can be retrieved in a snippet or build phase via
+@code{search-auxiliary-file}.
+When adding an auxiliary file, do not forget to also list it in
+@code{AUX_FILES} of @file{Makefile.am}.
 
 @node Emacs Packages
 @subsection Emacs Packages
-- 
2.37.0

Re: [PATCH v2] doc: Update contribution guidelines on patches, etc.

[Ludovic Courtès]

Hello,

Liliana Marie Prikler <liliana.prikler@gmail.com> skribis:

> * doc/contributing.texi ("Snippets versus Phases"): Replaced with...
> ("Modifying Sources"): ... this.  List more use cases and some principles.

It’s been a while; this looks like a nice improvement to me.  It’s a bit
long, but perhaps that’s avoidable.  If there are no objections, I’d say
go for it.

> +might be subjective, though it should lie somewhere between 10~20 lines.

Rather “10--20 lines” (Texinfo replaces dash-dash with an en dash).

Thanks!

Ludo’.

Re: [PATCH v2] doc: Update contribution guidelines on patches, etc.

[Maxime Devos]

[-- Attachment #1.1.1: Type: text/plain, Size: 913 bytes --]


On 02-09-2022 15:12, Ludovic Courtès wrote:
> Hello,
>
> Liliana Marie Prikler <liliana.prikler@gmail.com> skribis:
>
>> * doc/contributing.texi ("Snippets versus Phases"): Replaced with...
>> ("Modifying Sources"): ... this.  List more use cases and some principles.
> It’s been a while; this looks like a nice improvement to me.  It’s a bit
> long, but perhaps that’s avoidable.  If there are no objections, I’d say
> go for it.

Have you seen my v2? It has a somewhat different structure (the 'Problem 
-> solution’ structure proposed by Julien), Liliana's patch is more 
‘Solution -> relevant problems’.

Liliana's patch works too, but I would like to make sure you haven't 
overlooked my patch.

If Liliana's patch is preferred, we can go with that one, if my patch is 
preserved, I could look at addressing the comments on the wording for a v3.

Greetings,
Maxime.


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

Re: [PATCH v2] doc: Update contribution guidelines on patches, etc.

[Ludovic Courtès]

Hi,

Maxime Devos <maximedevos@telenet.be> skribis:

> On 02-09-2022 15:12, Ludovic Courtès wrote:
>> Hello,
>>
>> Liliana Marie Prikler <liliana.prikler@gmail.com> skribis:
>>
>>> * doc/contributing.texi ("Snippets versus Phases"): Replaced with...
>>> ("Modifying Sources"): ... this.  List more use cases and some principles.
>> It’s been a while; this looks like a nice improvement to me.  It’s a bit
>> long, but perhaps that’s avoidable.  If there are no objections, I’d say
>> go for it.
>
> Have you seen my v2?

I guess I haven’t (I was catching up with email as I returned from
vacation).

Hmm should you send the latest agreed-upon version to
guix-patches@gnu.org for clarity?

TIA,
Ludo’.

Re: [PATCH v2] doc: Update contribution guidelines on patches, etc.

[Maxime Devos]

[-- Attachment #1.1.1: Type: text/plain, Size: 920 bytes --]


On 05-09-2022 11:47, Ludovic Courtès wrote:
> Hi,
>
> Maxime Devos <maximedevos@telenet.be> skribis:
>
>> On 02-09-2022 15:12, Ludovic Courtès wrote:
>>> Hello,
>>>
>>> Liliana Marie Prikler <liliana.prikler@gmail.com> skribis:
>>>
>>>> * doc/contributing.texi ("Snippets versus Phases"): Replaced with...
>>>> ("Modifying Sources"): ... this.  List more use cases and some principles.
>>> It’s been a while; this looks like a nice improvement to me.  It’s a bit
>>> long, but perhaps that’s avoidable.  If there are no objections, I’d say
>>> go for it.
>> Have you seen my v2?
> I guess I haven’t (I was catching up with email as I returned from
> vacation).
>
> Hmm should you send the latest agreed-upon version to guix-patches@gnu.org for clarity?

I'll integrate the agreed-on changes into a v3 and merge some parts of 
Liliana' version and send it ...

Greetings,
Maxime


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

Re: [PATCH v2] doc: Update contribution guidelines on patches, etc.

[Maxime Devos]

[-- Attachment #1.1.1: Type: text/plain, Size: 1036 bytes --]


On 05-09-2022 15:12, Maxime Devos wrote:
>
> On 05-09-2022 11:47, Ludovic Courtès wrote:
>> Hi,
>>
>> Maxime Devos <maximedevos@telenet.be> skribis:
>>
>>> On 02-09-2022 15:12, Ludovic Courtès wrote:
>>>> Hello,
>>>>
>>>> Liliana Marie Prikler <liliana.prikler@gmail.com> skribis:
>>>>
>>>>> * doc/contributing.texi ("Snippets versus Phases"): Replaced with...
>>>>> ("Modifying Sources"): ... this.  List more use cases and some 
>>>>> principles.
>>>> It’s been a while; this looks like a nice improvement to me.  It’s 
>>>> a bit
>>>> long, but perhaps that’s avoidable.  If there are no objections, 
>>>> I’d say
>>>> go for it.
>>> Have you seen my v2?
>> I guess I haven’t (I was catching up with email as I returned from
>> vacation).
>>
>> Hmm should you send the latest agreed-upon version to 
>> guix-patches@gnu.org for clarity?
>
> I'll integrate the agreed-on changes into a v3 and merge some parts of 
> Liliana' version and send it ...

See: #57598.

Greetings,
Maxime.

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

Re: [PATCH] doc: Update contribution guidelines on patches, etc.

[Maxime Devos]

[-- Attachment #1.1.1: Type: text/plain, Size: 2585 bytes --]

On 06-08-2022 08:55, Liliana Marie Prikler wrote:

> +If your package has a bug that takes multiple lines to fix,
I don't think this is true for replacing all instances of "foo" by 
"/gnu/store/.../bin/foo" in a file.
>   or a fix
> +has already been accepted upstream, patches are the preferred way of
> +eliminating said bug
> +Refer to the @code{origin} record documentation
> +(particularly the fields @code{snippet} and @code{modules}), for more
> +information (@pxref{origin Reference}).
> +

The "Refer to the ... documentation for more information" occurred in 
the old version of (guix)Snippets versus Phases. However, back then, I 
did not find more information on how to decide between snippets, patches 
and phases, and neither do I now.

Maybe:

+Refer to the @code{origin} record documentation
+(@pxref{origin Reference}) (particularly the fields @code{snippet} and @code{modules})
+for more information on how to use snippets

, to avoid a reader's assumption that that section contains information 
on deciding between snippets, phases and patches.

> + Furthermore, as with patches, modifying the snippets causes two derivations to be built.

This is true, but I don't think reviewers and package authors have to 
worry about that.

> Such changes include, but are not limited to fixes of the
> +build script(s) or embeddings of store paths (e.g. replacement of
> +@file{/bin/sh} with @code{(search-input-file inputs "bin/sh")}).
Include what? I think you need to close the subsentence here:

> +Such changes include, but are not limited to, fixes of the build
> +script(s) or embeddings of store paths (e.g. [...])
>

[...]

> +Build phases are limited in that they do not modify the source
> +derivation.  Thus, they are inadequate for changes that are to be
> +reflected in the source code.  On the other hand, they only cause a
> +single rebuild and are thus slightly easier to debug than phases and
> +snippets.
Derivations are a rather low-level concept, could they be avoided in the 
origin and phases documentation?

> +Build phases are limited in that they do not modify the source
> +derivation.  Thus, they are inadequate for changes that are to be
> +reflected in the source code.  On the other hand, they only cause a
> +single rebuild and are thus slightly easier to debug than phases and
> +snippets.
See Andreas' comment on phase->snippet.

Also, do I understand correctly that the argument here is that 'single 
rebuild -> less compilation time -> easier to debug'?

Greetings,
Maxime.


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

Re: [PATCH] doc: Update contribution guidelines on patches, etc.

[Liliana Marie Prikler]

Am Dienstag, dem 09.08.2022 um 18:45 +0200 schrieb Maxime Devos:
> On 06-08-2022 08:55, Liliana Marie Prikler wrote:
> 
> > +If your package has a bug that takes multiple lines to fix,
> I don't think this is true for replacing all instances of "foo" by 
> "/gnu/store/.../bin/foo" in a file.
Should it?

> >   or a fix
> > +has already been accepted upstream, patches are the preferred way
> > of
> > +eliminating said bug
> > +Refer to the @code{origin} record documentation
> > +(particularly the fields @code{snippet} and @code{modules}), for
> > more
> > +information (@pxref{origin Reference}).
> > +
> 
> The "Refer to the ... documentation for more information" occurred in
> the old version of (guix)Snippets versus Phases. However, back then,
> I did not find more information on how to decide between snippets,
> patches and phases, and neither do I now.
> 
> Maybe:
> 
> +Refer to the @code{origin} record documentation
> +(@pxref{origin Reference}) (particularly the fields @code{snippet}
> and @code{modules})
> +for more information on how to use snippets
> 
> , to avoid a reader's assumption that that section contains
> information on deciding between snippets, phases and patches.
Yeah, this was meant for "how to use".

> > + Furthermore, as with patches, modifying the snippets causes two
> > derivations to be built.
> 
> This is true, but I don't think reviewers and package authors have to
> worry about that.
It does make a difference to the author when debugging their package. 
Starting with a phase and then moving it to a snippet can save good
time.

> > Such changes include, but are not limited to fixes of the
> > +build script(s) or embeddings of store paths (e.g. replacement of
> > +@file{/bin/sh} with @code{(search-input-file inputs "bin/sh")}).
> Include what? I think you need to close the subsentence here:
> 
> > +Such changes include, but are not limited to, fixes of the build
> > +script(s) or embeddings of store paths (e.g. [...])
> > 
> 
> [...]
Is that how to English comma?  Sorry, I'm not a native speaker so I get
somewhat weirded out by the when to skip/not to skip rules.

> > +Build phases are limited in that they do not modify the source
> > +derivation.  Thus, they are inadequate for changes that are to be
> > +reflected in the source code.  On the other hand, they only cause
> > a
> > +single rebuild and are thus slightly easier to debug than phases
> > and
> > +snippets.
> Derivations are a rather low-level concept, could they be avoided in
> the origin and phases documentation?
I don't quite see how.  You could s/source derivation/the result of
@code{guix build -S}/, but I don't think that's much better.

> > +Build phases are limited in that they do not modify the source
> > +derivation.  Thus, they are inadequate for changes that are to be
> > +reflected in the source code.  On the other hand, they only cause
> > a
> > +single rebuild and are thus slightly easier to debug than phases
> > and
> > +snippets.
> See Andreas' comment on phase->snippet.
> 
> Also, do I understand correctly that the argument here is that
> 'single rebuild -> less compilation time -> easier to debug'?
Easier to debug for the package author currently fiddling with the
phase/snippet.  Not really a statement in any direction otherwise.

Cheers

Re: [PATCH] doc: Update contribution guidelines on patches, etc.

[Maxime Devos]

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

> Am Dienstag, dem 09.08.2022 um 18:45 +0200 schrieb Maxime Devos:
>> On 06-08-2022 08:55, Liliana Marie Prikler wrote:
>>
>>> +If your package has a bug that takes multiple lines to fix,
>> I don't think this is true for replacing all instances of "foo" by
>> "/gnu/store/.../bin/foo" in a file.
> Should it?
I don't think so. Directly substituting all the instances instead of 
first writing a patch that does "foo" -> "@foo@" or such seems simpler 
to me.  This might be a bit too nit-picky though, maybe it's clear from 
context that this is not the kind of fix meant by that line.
>>> + Furthermore, as with patches, modifying the snippets causes two
>>> derivations to be built.
>> This is true, but I don't think reviewers and package authors have to
>> worry about that.
> It does make a difference to the author when debugging their package.
> Starting with a phase and then moving it to a snippet can save good
> time.
Hm, maybe, I guess I often work on 'small' packages where it doesn't 
matter much.

On 09-08-2022 19:05, Liliana Marie Prikler wrote:
>>> +Such changes include, but are not limited to, fixes of the build
>>> +script(s) or embeddings of store paths (e.g. [...])
>>>
>> [...]
> Is that how to English comma?  Sorry, I'm not a native speaker so I get
> somewhat weirded out by the when to skip/not to skip rules.
>
Neither am I. English doesn't seem to do "rules" much. I do think, 
however, that adding a comma after "to" makes things a bit simpler to 
read here, and it doesn't appear to be ungrammatical -- at least, in 
licenses "but is/are not limited to" is often used that way.

> Derivations are a rather low-level concept, could they be avoided in
> the origin and phases documentation?
> I don't quite see how.  You could s/source derivation/the result of
> @code{guix build -S}/, but I don't think that's much better.
>
To be clear, do you mean you:

  * think it's not better, maybe even worse
  * think it's not _much_ better (but still _slightly_ better)
  * are undecided
  * or something else

?

Also, "guix build -S" returns the source code (after snippet / patch, if 
any), not its derivation. For the latter: "guix build -S -d"

>>> +Build phases are limited in that they do not modify the source
>>> +derivation.  Thus, they are inadequate for changes that are to be
>>> +reflected in the source code.  On the other hand, they only cause
>>> a
>>> +single rebuild and are thus slightly easier to debug than phases
>>> and
>>> +snippets.
>> See Andreas' comment on phase->snippet.
>>
>> Also, do I understand correctly that the argument here is that
>> 'single rebuild -> less compilation time -> easier to debug'?
> Easier to debug for the package author currently fiddling with the
> phase/snippet.  Not really a statement in any direction otherwise.
I don't see how "slightly easier to debug than phases" follows from 
"they cause only a single rebuild". My guess was that the intermediate 
step was lower compilation time, but apparently this was not the 
argument. As such, I'm not following.

Greetings,
Maxime.


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

Re: [PATCH] doc: Update contribution guidelines on patches, etc.

[Liliana Marie Prikler]

Am Dienstag, dem 09.08.2022 um 20:19 +0200 schrieb Maxime Devos:
> > Am Dienstag, dem 09.08.2022 um 18:45 +0200 schrieb Maxime Devos:
> > 
> > > On 06-08-2022 08:55, Liliana Marie Prikler wrote:
> > > 
> > > 
> > > > +If your package has a bug that takes multiple lines to fix,
> > > I don't think this is true for replacing all instances of "foo"
> > > by 
> > > "/gnu/store/.../bin/foo" in a file.
> > Should it?
> I don't think so. Directly substituting all the instances instead of
> first writing a patch that does "foo" -> "@foo@" or such seems
> simpler to me.  This might be a bit too nit-picky though, maybe it's
> clear from context that this is not the kind of fix meant by that
> line.
I'm struggling to see the issue here.  For starters, it doesn't take
multiple lines to embed a store path, the change usually happens on a
single line.  Of course, translating this into a substitute*, you
expand this single line into multiple ones, but that's not what is
meant here.

However, there are exceptions to this rule.  For an example that
requires indirection, see webkitgtk.

> [...]
> > 
> > > > +Such changes include, but are not limited to, fixes of the
> > > > build
> > > > +script(s) or embeddings of store paths (e.g. [...])
> > > > 
> > > [...]
> > Is that how to English comma? Sorry, I'm not a native speaker so I
> > get
> > somewhat weirded out by the when to skip/not to skip rules.
> > 
> Neither am I. English doesn't seem to do "rules" much. I do think,
> however, that adding a comma after "to" makes things a bit simpler to
> read here, and it doesn't appear to be ungrammatical -- at least, in
> licenses "but is/are not limited to" is often used that way.
Fair enough, will add the comma.

> > Derivations are a rather low-level concept, could they be avoided
> > in the origin and phases documentation?
> > I don't quite see how. You could s/source derivation/the result of
> > @code{guix build -S}/, but I don't think that's much better.
> > 
> To be clear, do you mean you:
>  * think it's not better, maybe even worse
>  * think it's not _much_ better (but still _slightly_ better)
>  * are undecided
>  * or something else
> ?
> Also, "guix build -S" returns the source code (after snippet / patch,
> if any), not its derivation. For the latter: "guix build -S -d"
FWIW I don't think mentioning patch-and-repack is too helpful here
either.  Also, I'd like to use consistent wording at least within this
section, so here "source" means "upstream source" whereas "source
derivation" is a shorthand for the stuff Guix builds.  Yes, the
derivation is not the same thing as the output, but I again fail to see
how being overly precise is helpful.  That being said, I'm open to
suggestions.

> > > > +Build phases are limited in that they do not modify the source
> > > > +derivation.  Thus, they are inadequate for changes that are to
> > > > be
> > > > +reflected in the source code.  On the other hand, they only
> > > > cause
> > > > a
> > > > +single rebuild and are thus slightly easier to debug than
> > > > phases
> > > > and
> > > > +snippets.
> > > See Andreas' comment on phase->snippet.
> > > 
> > > Also, do I understand correctly that the argument here is that
> > > 'single rebuild -> less compilation time -> easier to debug'?
> > Easier to debug for the package author currently fiddling with the
> > phase/snippet. Not really a statement in any direction otherwise.
> I don't see how "slightly easier to debug than phases" follows from
> "they cause only a single rebuild". My guess was that the
> intermediate step was lower compilation time, but apparently this was
> not the argument. As such, I'm not following.
I think this follows from your "I only deal with small packages"
experience earlier.  In my experience, the sources that are more likely
to require patches or snippets to fix their... issues... are also the
ones that take larger time to patch and repack.  After all, you don't
have that much overhead unpacking a 7 gig blob that doesn't exist.

Cheers

Re: [PATCH] doc: Update contribution guidelines on patches, etc.

[Maxime Devos]

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


On 09-08-2022 21:08, Liliana Marie Prikler wrote:
>>>> On 06-08-2022 08:55, Liliana Marie Prikler wrote:
>>>>
>>>>
>>>>> +If your package has a bug that takes multiple lines to fix,
>>>> I don't think this is true for replacing all instances of "foo"
>>>> by
>>>> "/gnu/store/.../bin/foo" in a file.
>>> Should it?
>> I don't think so. Directly substituting all the instances instead of
>> first writing a patch that does "foo" -> "@foo@" or such seems
>> simpler to me.  This might be a bit too nit-picky though, maybe it's
>> clear from context that this is not the kind of fix meant by that
>> line.
> I'm struggling to see the issue here.  For starters, it doesn't take
> multiple lines to embed a store path, the change usually happens on a
> single line.  Of course, translating this into a substitute*, you
> expand this single line into multiple ones, but that's not what is
> meant here.

I was thinking of files that contain multiple instances of "foo" 
(usually on multiple lines) to be replaced by "/gnu/store/.../bin/foo", 
not files were a "foo
bar" was broken over multiple lines and it needs to be replaced by 
"/gnu/store/.../bin/foo
bar".

At least for the former, I don't think an intermediate "@foo@" is useful 
(with some exceptions, when a pattern match would catch too much).

The latter could in principle happen, but it doesn't seem to happen in 
practice.

Greetings,
Maxime.


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

Re: [PATCH] doc: Update contribution guidelines on patches, etc.

[Liliana Marie Prikler]

Am Dienstag, dem 09.08.2022 um 22:30 +0200 schrieb Maxime Devos:
> 
> On 09-08-2022 21:08, Liliana Marie Prikler wrote:
> > [I]t doesn't take multiple lines to embed a store path, the change
> > usually happens on a single line
> I was thinking of files that contain multiple instances of "foo"
> (usually on multiple lines) to be replaced by
> "/gnu/store/.../bin/foo", not files were a "foo
>  bar" was broken over multiple lines and it needs to be replaced by
> "/gnu/store/.../bin/foo
>  bar".
That's a single-line change imho, even if the single line gets repeated
9000 times.

Cheers

Re: [PATCH] doc: Update contribution guidelines on patches, etc.

[Maxime Devos]

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


On 09-08-2022 21:08, Liliana Marie Prikler wrote:
>> To be clear, do you mean you:
>>   * think it's not better, maybe even worse
>>   * think it's not_much_  better (but still_slightly_  better)
>>   * are undecided
>>   * or something else
>> ?
>> Also, "guix build -S" returns the source code (after snippet / patch,
>> if any), not its derivation. For the latter: "guix build -S -d"
> FWIW I don't think mentioning patch-and-repack is too helpful here
> either.  Also, I'd like to use consistent wording at least within this
> section, so here "source" means "upstream source" whereas "source
> derivation" is a shorthand for the stuff Guix builds.  Yes, the
> derivation is not the same thing as the output, but I again fail to see
> how being overly precise is helpful.  That being said, I'm open to
> suggestions.
>
I am not reading an answer to my question.

I don't think I've mentioned patch-and-repack (at least not by name, 
which you seem to be referring to?).

I would not recommend "source = upstream source", as the more general 
meaning is used in (guix)Introduction and 
<https://www.gnu.org/philosophy/free-sw.html> and elsewhere, otherwise 
terminology would become inconsistent, which can lead to misinterpretations.

I don't think there's such a thing as 'overly precise'.

My suggestion is the same as your suggestion:

> You could s/source derivation/the result of
> @code{guix build -S}/, but I don't think that's much better.
Greetings,
Maxime.


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

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

[Andreas Enge]

Hello,

Am Fri, Aug 05, 2022 at 03:59:14PM +0200 schrieb Maxime Devos:
> Here's a v2. I've changed the structure to something close to what Julien
> proposed, it looks a lot better now to me!

thanks, it does! I still find it a bit too verbose compared to Liliana's
suggestion, which I would prefer as a starting point of the discussion.

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

Do you mean "phase" here instead of "snippet"? That is what I usually do...
My practice is to use a patch when the goal is to eventually change the
source code upstream (or it is already changed upstream and we can take a
patch from their git repo, say), and a phase when one cannot expect upstream
to incorporate the changes since they are specific to Guix (like embedding
store paths, as Liliana writes, where apparently a phase is the only option
anyway).

Andreas

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

[Maxime Devos]

[-- Attachment #1.1.1: Type: text/plain, Size: 1797 bytes --]


On 08-08-2022 23:51, Andreas Enge wrote:
> Hello,
>
> Am Fri, Aug 05, 2022 at 03:59:14PM +0200 schrieb Maxime Devos:
>> Here's a v2. I've changed the structure to something close to what Julien
>> proposed, it looks a lot better now to me!
> thanks, it does! I still find it a bit too verbose compared to Liliana's
> suggestion, which I would prefer as a starting point of the discussion.

WDYM with 'still' here? The v2 patch I sent preceded Liliana's patch.

I'm not seeing a 'too verbose'-ity or a difference in verbosity myself

---

Something I liked about Julien's proposed structure is:

> [...] derive rules for specific cases, based on these principles:
>
> How do I remove non-free software? -> snippet because …
>
> How do I remove bundled libraries? -> snippet or phase because …
>
> How do I fix a build issue? -> patch or snippet if this affects 
> building from source, can also be a phase if the result of --sources 
> can still build
>
> A test issue?
>
> …
>
> This leaves some cases up to interpretation, but that's probably not 
> so different from "it's not an absolute rule". It's also much clearer 
> and quicker to figure out in which case you are. If not documented as 
> a case, you can fall back to the general principles.
-- i.e., if I want to do $FOO, I could quickly find out how to do it.  
In the v2 I sent, this was reflected in the subsections, each subsection 
is a 'howto $FOO'. Whereas the patch Liliana sent is kind of the inverse 
-- each @item corresponds to a 'what can the method $FOO be used for'. 
Similarly, in the v1 I sent, I followed a similar structure (an item for 
patches, an item for snippets, an item for phases).

As such, the v2 I sent seems a better basis to me.

Greetings,
Maxime.


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

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

[Andreas Enge]

Am Tue, Aug 09, 2022 at 05:06:43PM +0200 schrieb Maxime Devos:
> WDYM with 'still' here? The v2 patch I sent preceded Liliana's patch.

I meant that I prefer it to your v1 patch, but still find it too verbose.

Andreas

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

[Maxime Devos]

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


On 08-08-2022 23:51, Andreas Enge wrote:
>> 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.
> Do you mean "phase" here instead of "snippet"? That is what I usually do...
> My practice is to use a patch when the goal is to eventually change the
> source code upstream (or it is already changed upstream and we can take a
> patch from their git repo, say), and a phase when one cannot expect upstream
> to incorporate the changes since they are specific to Guix (like embedding
> store paths, as Liliana writes, where apparently a phase is the only option
> anyway).

I meant 'snippet' in this subsubsection. Bugfixes seem useful to have in 
the result of "guix build --source", and appear to be required to be in 
there for the 'corresponding source' thing.

Greetings,
Maxime.


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

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

[Andreas Enge]

Am Mon, Sep 05, 2022 at 03:03:34PM +0200 schrieb Maxime Devos:
> I meant 'snippet' in this subsubsection. Bugfixes seem useful to have in the
> result of "guix build --source", and appear to be required to be in there for
> the 'corresponding source' thing.

If we distribute the upstream source (as a "binary" substitute) and the
patch (through the Guix sources), my impression is that we do publish the
corresponding source.

Andreas

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

[Maxime Devos]

[-- Attachment #1.1.1: Type: text/plain, Size: 949 bytes --]


On 07-09-2022 14:17, Andreas Enge wrote:
> Am Mon, Sep 05, 2022 at 03:03:34PM +0200 schrieb Maxime Devos:
>> I meant 'snippet' in this subsubsection. Bugfixes seem useful to have in the
>> result of "guix build --source", and appear to be required to be in there for
>> the 'corresponding source' thing.
> If we distribute the upstream source (as a "binary" substitute) and the
> patch (through the Guix sources), my impression is that we do publish the
> corresponding source.

Well, yes, but just sharing "guix build --sources=transitive ..." is 
more convenient than having to include a copy of Guix as well. And for 
people unpacking the result of "guix build --source ..." + "guix shell 
-D ...", having the bugfixes (where possible) included in there is 
convenient.

So yes, not strictly required, but I do consider including the fixes in 
the 'source' field (where possible) to be more practical.

Greetings,
Maxime.


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

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

[david larsson]

On 2022-08-05 15:59, Maxime Devos wrote:

[..]

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

There may be other reasons to add patches:

1. Functionality, that is not yet accepted upstream, because 
maintainer(s) do not have enough time to review all pull requests, or 
are simply slow to review. "if no response within X time from upstream, 
then guix may include your patch" might be a good policy here.

2. Bug fixes - as you mentioned - for such, it might be good with a: "if 
no response within X time from upstream, then guix may include your 
bug-fix patch".

3. Unmaintained projects - sometimes there are packages that are nice to 
include but which may no longer be maintained by upstream, and a few 
patches could still make the package usable and nice to have for Guix 
users. IMO such packages should generally be accepted, including minor 
patches that enhances the package. Examples would include guile-bash, 
and maybe emacs-company-tern (not in guix, but might be nice to have). 
There are probably more examples.

Im not a guix maintainer, so maintaining above varieties of patches 
might not be feasible, but there are potential benefits, like maybe guix 
is just "nicer" than other distros because of it. Or it might have the 
opposite effect if the maintenance burden is too high. Guix should 
spread more to mainstream IMO, and being able accept patches that are 
"nice", would benefit that purpose.

Best regards,
David

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

[Maxime Devos]

[-- Attachment #1.1.1: Type: text/plain, Size: 2341 bytes --]


On 09-08-2022 20:58, david larsson wrote:
> On 2022-08-05 15:59, Maxime Devos wrote:
>
> [..]
>
>>
>> 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.
>
> There may be other reasons to add patches: [...]

Agreed (*), but I don't think that subsection claims those are the only 
reasons for patches -- that section is only about fixing technical 
issues, not adding new features, as implied by the name of the section.

I can look at adding a new subsection 'Adding new functionality' for a v3.

Liliana's documentation contains some information not in my v2, I intend 
to look into integrating that information as well.

>
> 1. Functionality, that is not yet accepted upstream, because 
> maintainer(s) do not have enough time to review all pull requests, or 
> are simply slow to review. "if no response within X time from 
> upstream, then guix may include your patch" might be a good policy here.

(*) We sometimes do such things already. Example: 
<https://issues.guix.gnu.org/49828> (nowadays upstreamed). I don't think 
this thread is a good place for deciding on the exact rules though -- 
deciding on an appropriate value of X seems difficult, I would like to 
separate that from the current documentation patch.

Greetings,
Maxime.

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

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

[david larsson]

On 2022-08-09 22:53, Maxime Devos wrote:

> 
> Agreed (*), but I don't think that subsection claims those are the
> only reasons for patches -- that section is only about fixing
> technical issues, not adding new features, as implied by the name of
> the section.

It definitely doesn't claim that. I phrased it poorly I think.

> 
> I can look at adding a new subsection 'Adding new functionality' for a 
> v3.
> 
> Liliana's documentation contains some information not in my v2, I
> intend to look into integrating that information as well.

Thanks, that sounds great!

Best regards,
David

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

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

[Maxime Devos]

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


On 05-08-2022 18:59, blake@reproduciblemedia.com wrote:
> Hi Maxime,
>
> Adding some basic grammatical corrections below:
I have read several proposed corrections, but most of them don't appear 
to be grammatical corrections but rather stylistic or about 
(non-grammar) clarity or contents.
> August 5, 2022 1:59 PM, "Maxime Devos"<maximedevos@telenet.be>  wrote:
>
>
> 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---
>
I consider the difference between referring to external source code by 
including a (snippet-sanitised) copy or downloading it from an URL + 
snippet-sanitising to be immaterial, except for space and I/O savings, 
so I consider "has" to include "distributes".

While "distributes" is more specific, I really meant "has" here -- 
gnu/packages/patches/... and gnu/packages/*.scm must be free too, even 
if it is was not a distributed package (more concretely, see the bits 
about patches failing to remove non-freeness).

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

You write that the addendum is redundant, but then change the addendum 
by replacing a word in the addendum by a possible definition. I'm not 
following how that reduces redundancy, and it also appears to be 
contrary to the lack of verbosity that Andreas would like.

>> * 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 be clear, this is to replace the third point (Sometimes, there's more 
than one way to do it, etc.), without removing the previous two?

I would not use combinations like 'presented with a variety of 
strategies' however, I don't think that leads to clarity. Also, the 
preferences of 'you' are not all that important here, it's what they 
choose for that's important even if it is not their preference. (Though 
the two coinciding would be ideal of course!) Maybe:

When there is more than one way to do something, choose whichever method is the simplest.
Sometimes this is subjective, which is also fine. What matters is that you use techniques that
are common within the community (i.e. patterns that appear throughout gnu/packages/...) and
are thus clearly legible for reviewers.

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

I don't see how a fancy wording amounting to essentially the same thing 
would reduce confusion or avoid latent assumptions.

Anyway, I'm not seeing any assumption that they are already familiar 
with the Guix workflow -- the point of such sections is to explain the 
workflow, people already familiar aren't expected to read it (at least, 
not often). I don't see how it would lead to confusion, because it 
doesn't allude to any principles in particular, because the text isn't 
some kind of analysis on principles and their interactions but a howto 
of sorts, and because it points to the cases below.

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

The purpose of the hypothetical patch or phase is to remove the 
non-freeness. As such, if the non-freeness wasn't removed, the patch or 
phase did not work, for the local meaning of "working". This is 
machine-independent (so no "it might work on their machine"), unless 
there is some kind of non-determinism, but I haven't ever noticed that 
happening for non-freeness removal code.

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

Why the change:

  * singular->plural (for: patch) -- is this to reduce the wordcount
    (avoid an 'a'), or for consistency, or ...?
  * passive->active (for: removing -> that removes) -- it becomes more
    wordy, so seems harder to follow for me
  * appear->be distributed -- more wordy, also things parts of Guix
    itself  (and hence not distributed, except for "guix build guix" and
    "guix pull") should be free so I don't think being more specific
    makes things more precise.
  * "only in its patches" -> "if it only appears within the context of a
    patch" -- more wordy, and more indirection
  * "For a phases" -> "Concerning phases"  -- slightly less direct

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

While I would like upstreams to care about additional maintenance costs 
downstream, I do not think we have proof of that at the moment, so I 
would stick with the meaning of the original sentence -- I used 
'upstream' as a verb here, not as a noun.

However, I could look into reformulating the sentence a bit to avoid 
reading it as a noun and hence avoid backtracing when parsing that sentence?

>   As upstream cannot accept a snippet, writing a patch can be a
There's more than one upstream as Guix has multiple packages, so the 
plural "upstreams" seems more correct to me, though I wouldn't consider 
the singular to be incorrect.  I have however, in some other places used 
singular for something of which there exist multiple instances, so I'll 
look at making the wording consistent one way or the other.
> 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,

Right, I already introduces a store file name, and that "otherwise" 
refers to the same store file name.

"the store file name" is singular, so ^W^W -- nevermind, that's a 
subjunctive? I would go for the simpler "i fthe store file name were 
embedded in the source", dropping the 'to be' indirection.

Question: do you know how to decide between "if X were to be 
embedded"/"if X were embedded" and "if X was embedded"?

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

The Oxford comma or lack thereof are acceptable stylistic conventions, 
but not a grammatical error. There are only two conjucts here though, so 
I don't think the Oxford comma applies here. Additionally, the two 
conjucts are about mostly the same thing, but just different (similar!) 
subcases that merely happen to need different qualifications (unusable 
on non-Guix vs. likely unusable on different-arch Guix), so I don't 
think that 'also' brings something here.

Greetings,
Maxime.

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

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

[Maxime Devos]

[-- Attachment #1.1.1: Type: text/plain, Size: 934 bytes --]


On 09-08-2022 18:30, Maxime Devos wrote:
>>   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---
>
> The Oxford comma or lack thereof are acceptable stylistic conventions, 
> but not a grammatical error. There are only two conjucts here though, 
> so I don't think the Oxford comma applies here. Additionally, the two 
> conjucts are about mostly the same thing, but just different 
> (similar!) subcases that merely happen to need different 
> qualifications (unusable on non-Guix vs. likely unusable on 
> different-arch Guix), so I don't think that 'also' brings something here.
>
Oops, the 'also' was present in the original. I removed 'also', but 
found it to be more readable with 'also', so I'm keeping 'also' anyways.

Greetings,
Maxime.


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

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

[blake]

Hi Maxime,

August 9, 2022 4:30 PM, "Maxime Devos" <maximedevos@telenet.be> wrote:

> On 05-08-2022 18:59, blake@reproduciblemedia.com wrote:
> 
>> Hi Maxime,
>> Adding some basic grammatical corrections below:
> 
> I have read several proposed corrections, but most of them don't appear to be grammatical
> corrections but rather stylistic or about (non-grammar) clarity or contents.

Yes, there are stylistic suggestions as well -- well-formed writing isn't merely a matter of
grammar, but also stylistic consistency. But thats not to say style is merely a subjective
matter of preference; this is based on years as a philosophy PhD reviewing students and
colleagues' papers, which requires that one becomes intimate with all of the major style guides
that set the standard rules for editing the English language.

If I just said "making some basic grammatical edits", its because I was reading the email,
realized many improvements could be added and wanted to get through it quick so that I could
have time for it in the first place. Just trying to help with something I'm quite skilled in.

>> August 5, 2022 1:59 PM, "Maxime Devos" <maximedevos@telenet.be> wrote:
>> 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---
> 
> I consider the difference between referring to external source code by including a
> (snippet-sanitised) copy or downloading it from an URL + snippet-sanitising to be immaterial,
> except for space and I/O savings, so I consider "has" to include "distributes".
> 
> While "distributes" is more specific, I really meant "has" here -- gnu/packages/patches/... and
> gnu/packages/*.scm must be free too, even if it is was not a distributed package (more concretely,
> see the bits about patches failing to remove non-freeness).
> 
> [...]

This is simply a grammatical error. "Has" is third person singular. While its common to speak
in such a way, it's not proper English, and including minor slang should be avoided in technical
writing. Otherwise inconsistency of presentation is guaranteed, causing serious overhead for
readers.

>> 
> 
> * 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---
> 
> You write that the addendum is redundant, but then change the addendum by replacing a word in the
> addendum by a possible definition. I'm not following how that reduces redundancy, and it also
> appears to be contrary to the lack of verbosity that Andreas would like.

Redundancy in language is information expressed more than once. Including redundant clauses
is bad grammar[1]

You wrote:
> The source of the package needs to correspond to what is actually built (i.e., act as the
> corresponding source)

You simply said the same thing twice. It is by definition, a redundant clause.

> then change the addendum by replacing a word in the
> addendum by a possible definition.

Elaboration doesnt necessarily add redunancy, it is useful for clarifying statements. I was
trying to infer your intention in adding the clause, to offer an example of how it could be
more clearly stated.

[1] https://en.wikipedia.org/wiki/Redundancy_(linguistics)

> * 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 be clear, this is to replace the third point (Sometimes, there's more than one way to do it,
> etc.), without removing the previous two?

Only for the third point.

> I would not use combinations like 'presented with a variety of strategies' however, I don't think
> that leads to clarity. Also, the preferences of 'you' are not all that important here, it's what
> they choose for that's important even if it is not their preference. (Though the two coinciding
> would be ideal of course!) Maybe:
> 
> When there is more than one way to do something, choose whichever method is the simplest.
> Sometimes this is subjective, which is also fine. What matters is that you use techniques that
> are common within the community (i.e. patterns that appear throughout gnu/packages/...) and
> are thus clearly legible for reviewers.

Yeah thats great.

> 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---
> 
> I don't see how a fancy wording amounting to essentially the same thing would reduce confusion or
> avoid latent assumptions.

We have to consider how the audience will be experiencing the documentation. Are they reading it
like a novel, tuned in to each step of the process, or are they briefly approaching a paragraph
at a time, trying to quickly gather information for how to accomplish what they need so that they
can return to their work?

While we should seek to reduce verbosity, which means reducing the inclusion of unnecessary
information, we should also be optimizing each paragraph to be self-contained snapshots, lacking
ambiguity. I addressed this in my Guix Days talk, and most people seemed to agree with that point.

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

No "principals" had yet been explicitly addressed. If I stumble onto this sentence in isolation, I
will have have to ask: "What conflicts and principles?". By being explicit, we optimize towards a
"snapshot" that can be better understood in isolation.

The term "subjective variation" may be obtuse. I chose it in order to concisely say "... and
reducing friction in the review process introduced by several autonomous individuals with
distinct programming practices and backgrounds working together on a collective project".

I think it does the work, but others may disagree.

> Anyway, I'm not seeing any assumption that they are already familiar with the Guix workflow -- the
> point of such sections is to explain the workflow, people already familiar aren't expected to read
> it (at least, not often). I don't see how it would lead to confusion, because it doesn't allude to
> any principles in particular, because the text isn't some kind of analysis on principles and their
> interactions but a howto of sorts, and because it points to the cases below.

Its simply a matter of ambiguity vs. explication. I think we should choose more explicit wording
where possible. I can't count the number of times I have had to read an entire article in the
documentation just so that I could understand a later paragraph's latent assumption that I was
reading in a linear manner.

> 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---
> 
> The purpose of the hypothetical patch or phase is to remove the non-freeness. As such, if the
> non-freeness wasn't removed, the patch or phase did not work, for the local meaning of "working".
> This is machine-independent (so no "it might work on their machine"), unless there is some kind of
> non-determinism, but I haven't ever noticed that happening for non-freeness removal code.
> 
> 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---
> 
> Why the change:
> 
> * singular->plural (for: patch) -- is this to reduce the wordcount (avoid an 'a'), or for
> consistency, or ...?
> * passive->active (for: removing -> that removes) -- it becomes more wordy, so seems harder to
> follow for me

"Removing" is here a gerund, which shouldn't be applied to objects. This is a grammatical error.
The sentences as a whole were adjusted to accommodate the correction.

> * appear->be distributed -- more wordy, also things parts of Guix itself (and hence not
> distributed, except for "guix build guix" and "guix pull") should be free so I don't think being
> more specific makes things more precise.

I'm not attached to using distributed over "appears", it just seems more explicit.

> * "only in its patches" -> "if it only appears within the context of a patch" -- more wordy, and
> more indirection
> * "For a phases" -> "Concerning phases" -- slightly less direct

We're here discussing a general indefinite case, and thus the plural form is more proper.

> 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.
> 
> While I would like upstreams to care about additional maintenance costs downstream, I do not think
> we have proof of that at the moment, so I would stick with the meaning of the original sentence --
> I used 'upstream' as a verb here, not as a noun.
> 
> However, I could look into reformulating the sentence a bit to avoid reading it as a noun and hence
> avoid backtracing when parsing that sentence?

Yeah I'd agree that would be more clear.

>> As upstream cannot accept a snippet, writing a patch can be a
> 
> There's more than one upstream as Guix has multiple packages, so the plural "upstreams" seems more
> correct to me, though I wouldn't consider the singular to be incorrect. I have however, in some
> other places used singular for something of which there exist multiple instances, so I'll look at
> making the wording consistent one way or the other.
>> 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,
> 
> Right, I already introduces a store file name, and that "otherwise" refers to the same store file
> name.
> 
> "the store file name" is singular, so ^W^W -- nevermind, that's a subjunctive? I would go for the
> simpler "if the store file name were embedded in the source", dropping the 'to be' indirection.

That sounds good to me.

> Question: do you know how to decide between "if X were to be embedded"/"if X were embedded" and "if
> X was embedded"?

1st case: evokes future anterior; predication is contingent & retroactive. Should be used in
indeterminate circumstances.
2nd case: predication is determined by the present. We can know at present whether x is currently
embedded.
3rd case: predication is determined by the past. We can know whether x was *ever* embedded.

Why?

>> 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---
> 
> The Oxford comma or lack thereof are acceptable stylistic conventions, but not a grammatical error.
> There are only two conjucts here though, so I don't think the Oxford comma applies here.
> Additionally, the two conjucts are about mostly the same thing, but just different (similar!)
> subcases that merely happen to need different qualifications (unusable on non-Guix vs. likely
> unusable on different-arch Guix), so I don't think that 'also' brings something here.
> 
> Greetings,
> Maxime.

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

[Maxime Devos]

[-- Attachment #1.1.1: Type: text/plain, Size: 12713 bytes --]


On 10-08-2022 08:10, blake@reproduciblemedia.com wrote:
>>> August 5, 2022 1:59 PM, "Maxime Devos" <maximedevos@telenet.be> wrote:
>>> 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---
>> I consider the difference between referring to external source code by including a
>> (snippet-sanitised) copy or downloading it from an URL + snippet-sanitising to be immaterial,
>> except for space and I/O savings, so I consider "has" to include "distributes".
>>
>> While "distributes" is more specific, I really meant "has" here -- gnu/packages/patches/... and
>> gnu/packages/*.scm must be free too, even if it is was not a distributed package (more concretely,
>> see the bits about patches failing to remove non-freeness).
>>
>> [...]
> This is simply a grammatical error. "Has" is third person singular. While its common to speak
> in such a way, it's not proper English, and including minor slang should be avoided in technical
> writing. Otherwise inconsistency of presentation is guaranteed, causing serious overhead for
> readers.

"Has" is third person singular, and "Guix" is singular and not "I" or 
"you", so "has" seems appropriate here to me.

I think that matching the singular/plural of the verb and the subject is 
common, standard and proper English and not slang.

Going by previous replies, you seem to know English well, so I think 
there's some miscommunication here.

(Even better would be to replace the rather generic ‘to have’ by 
something more specific, but I'll have to think a bit about what would 
be more specific yet not overly specific.)

>
>> * 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---
>> You write that the addendum is redundant, but then change the addendum by replacing a word in the
>> addendum by a possible definition. I'm not following how that reduces redundancy, and it also
>> appears to be contrary to the lack of verbosity that Andreas would like.
> Redundancy in language is information expressed more than once. Including redundant clauses
> is bad grammar[1]
>
> You wrote:
>> The source of the package needs to correspond to what is actually built (i.e., act as the
>> corresponding source)
> You simply said the same thing twice. It is by definition, a redundant clause.
>
>> then change the addendum by replacing a word in the
>> addendum by a possible definition.
> Elaboration doesnt necessarily add redunancy, it is useful for clarifying statements. I was
> trying to infer your intention in adding the clause, to offer an example of how it could be
> more clearly stated.
>
> [1] https://en.wikipedia.org/wiki/Redundancy_(linguistics)

The purpose of 'i.e.' constructs is to state the same thing differently, 
to clarify matters (by elaboration or by redundancy). I don't see how 
redundancy is bad, though it can easily be overdone.

I think that explicitly mentioning the term 'corresponding source' 
instead of only the more implicit 'source of X corresponds to Y', 
because the former 'corresponding source' has a very specific meaning 
(*) in free software, whereas the latter construct is more ambiguous.

Compare with your definition 'there must be an explicit relation ...’, 
which loses a lot of nuance.

(*) E.g., the GPL has a long and detailed definition: ‘The 
"Corresponding Source" for a work in object code form means all the 
source code needed to generate, install, [lots and lots of text]’.

I can look into inserting a footnote linking to the GPL or copyleft.org 
or such, to make clear "corresponding source" is a term on its own and 
not just some description, for people that don't already know about 
"corresponding source".

>
>> 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---
>> I don't see how a fancy wording amounting to essentially the same thing would reduce confusion or
>> avoid latent assumptions.
> We have to consider how the audience will be experiencing the documentation. Are they reading it
> like a novel, tuned in to each step of the process, or are they briefly approaching a paragraph
> at a time, trying to quickly gather information for how to accomplish what they need so that they
> can return to their work?
>
> While we should seek to reduce verbosity, which means reducing the inclusion of unnecessary
> information, we should also be optimizing each paragraph to be self-contained snapshots, lacking
> ambiguity. I addressed this in my Guix Days talk, and most people seemed to agree with that point.
>
>> To make things more concrete and to resolve conflicts between the principles a few cases have been
>> worked out:
> No "principals" had yet been explicitly addressed.
Assuming that principals = principles, those principles have already 
been mentioned above -- see the bullet list in 20.4.5. But yes, the 
conflicts have not yet been addressed and aren't anywhere.
> If I stumble onto this sentence in isolation, I
> will have have to ask: "What conflicts and principles?". By being explicit, we optimize towards a
> "snapshot" that can be better understood in isolation.
>
> The term "subjective variation" may be obtuse. I chose it in order to concisely say "... and
> reducing friction in the review process introduced by several autonomous individuals with
> distinct programming practices and backgrounds working together on a collective project".
>
> I think it does the work, but others may disagree.

I do not see how your wording is more explicit than mine.

While I did not mention what the conflicts were, neither are you 
mentioning (in the text itself) what the "subjective variations" would be.

I don't think you have to ask "What conflicts", as the more frequent 
cases have been worked out below, resolving the potential conflicts. 
There might be some conflicts remaining, but it's hard to write about 
conflicts of which I don't know that they exist, and if they are known 
to exist, I think it would be better to resolve the conflicts (with a 
few new worked-out cases) and that way remove them from existence.

I'll have a try at rewording things in the next version to avoid 
implicitness and ambiguity, though I do not expect success.

Additionally, I don't see why this sentence has to be understood in 
isolation but not the first two sentences ‘Snippets, phases and patches 
at times serve overlapping purposes. To decide between the three, there 
are a few guiding principles:’.

>> [...]
>> The purpose of the hypothetical patch or phase is to remove the non-freeness. As such, if the
>> non-freeness wasn't removed, the patch or phase did not work, for the local meaning of "working".
>> This is machine-independent (so no "it might work on their machine"), unless there is some kind of
>> non-determinism, but I haven't ever noticed that happening for non-freeness removal code.
>>
>> 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---
>> Why the change:
>>
>> * singular->plural (for: patch) -- is this to reduce the wordcount (avoid an 'a'), or for
>> consistency, or ...?
>> * passive->active (for: removing -> that removes) -- it becomes more wordy, so seems harder to
>> follow for me
> "Removing" is here a gerund, which shouldn't be applied to objects. This is a grammatical error.
> The sentences as a whole were adjusted to accommodate the correction.

I don't know how this form of a verb would be classified in English. I 
don't see why "removing" shouldn't be applied to objects and I don't see 
how it is a grammatical error; that construct parses fine for me. It's a 
bogus construct in my native language but it seems to work well in English.

>> * appear->be distributed -- more wordy, also things parts of Guix itself (and hence not
>> distributed, except for "guix build guix" and "guix pull") should be free so I don't think being
>> more specific makes things more precise.
> I'm not attached to using distributed over "appears", it just seems more explicit.
I'll try looking for a more explicit word that is not too specific.
>
>> * "only in its patches" -> "if it only appears within the context of a patch" -- more wordy, and
>> more indirection
>> * "For a phases" -> "Concerning phases" -- slightly less direct
> We're here discussing a general indefinite case, and thus the plural form is more proper.

Is "general indefinite case" grammatical terminology or a description? 
For the former: I'm not finding any relevant search results.

I am not following how you go from "a general indefinite case" to "thus 
the plural it is more proper". A plural seems to be more common in these 
situations and doesn't seem to cause trouble here so I think I'll switch 
to a plural in the next version, but I don't see how it is more proper.

> [...]
>>> 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,
>> Right, I already introduces a store file name, and that "otherwise" refers to the same store file
>> name.
>>
>> "the store file name" is singular, so ^W^W -- nevermind, that's a subjunctive? I would go for the
>> simpler "if the store file name were embedded in the source", dropping the 'to be' indirection.
> That sounds good to me.
>
>> Question: do you know how to decide between "if X were to be embedded"/"if X were embedded" and "if
>> X was embedded"?
> 1st case: evokes future anterior; predication is contingent & retroactive. Should be used in
> indeterminate circumstances.
> 2nd case: predication is determined by the present. We can know at present whether x is currently
> embedded.
> 3rd case: predication is determined by the past. We can know whether x was *ever* embedded.
>
> Why?

I was wondering if the 2nd case is considered correct grammar (even if 
maybe not appropriate in this particular case) or just a personal quirk. 
Also, when learning English grammar, it was more based on 'feel' than 
explicit rules and consequently it was hard to decide between (2) and (3).

I don't know about (1), but (3) indeed doesn't seem appropriate here.

I'll change it to (2) in the next version.

Greetings,
Maxime.


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

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

[blake]

None of the edits I made were in criticism. In an academic context a proof reader would mark
almost all the same sentences for revision.

August 10, 2022 9:06 AM, "Maxime Devos" <maximedevos@telenet.be> wrote:

> On 10-08-2022 08:10, blake@reproduciblemedia.com wrote:
> 
>> August 5, 2022 1:59 PM, "Maxime Devos" <maximedevos@telenet.be> wrote:
>> 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---
>>> I consider the difference between referring to external source code by including a
>>> (snippet-sanitised) copy or downloading it from an URL + snippet-sanitising to be immaterial,
>>> except for space and I/O savings, so I consider "has" to include "distributes".
>>> 
>>> While "distributes" is more specific, I really meant "has" here -- gnu/packages/patches/... and
>>> gnu/packages/*.scm must be free too, even if it is was not a distributed package (more concretely,
>>> see the bits about patches failing to remove non-freeness).
>>> 
>>> [...]
>> 
>> This is simply a grammatical error. "Has" is third person singular. While its common to speak
>> in such a way, it's not proper English, and including minor slang should be avoided in technical
>> writing. Otherwise inconsistency of presentation is guaranteed, causing serious overhead for
>> readers.
> 
> "Has" is third person singular, and "Guix" is singular and not "I" or
> "you", so "has" seems appropriate here to me.
> 
> I think that matching the singular/plural of the verb and the subject is
> common, standard and proper English and not slang.
> 
> Going by previous replies, you seem to know English well, so I think
> there's some miscommunication here.
> 
> (Even better would be to replace the rather generic ‘to have’ by
> something more specific, but I'll have to think a bit about what would
> be more specific yet not overly specific.)
> 
>>> * 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---
>>> You write that the addendum is redundant, but then change the addendum by replacing a word in the
>>> addendum by a possible definition. I'm not following how that reduces redundancy, and it also
>>> appears to be contrary to the lack of verbosity that Andreas would like.
>> 
>> Redundancy in language is information expressed more than once. Including redundant clauses
>> is bad grammar[1]
>> 
>> You wrote:
>>> The source of the package needs to correspond to what is actually built (i.e., act as the
>>> corresponding source)
>> 
>> You simply said the same thing twice. It is by definition, a redundant clause.
>> 
>>> then change the addendum by replacing a word in the
>>> addendum by a possible definition.
>> 
>> Elaboration doesnt necessarily add redunancy, it is useful for clarifying statements. I was
>> trying to infer your intention in adding the clause, to offer an example of how it could be
>> more clearly stated.
>> 
>> [1] https://en.wikipedia.org/wiki/Redundancy_(linguistics)
> 
> The purpose of 'i.e.' constructs is to state the same thing differently,
> to clarify matters (by elaboration or by redundancy). I don't see how
> redundancy is bad, though it can easily be overdone.
> 
> I think that explicitly mentioning the term 'corresponding source'
> instead of only the more implicit 'source of X corresponds to Y',
> because the former 'corresponding source' has a very specific meaning
> (*) in free software, whereas the latter construct is more ambiguous.
> 
> Compare with your definition 'there must be an explicit relation ...’,
> which loses a lot of nuance.
> 
> (*) E.g., the GPL has a long and detailed definition: ‘The
> "Corresponding Source" for a work in object code form means all the
> source code needed to generate, install, [lots and lots of text]’.
> 
> I can look into inserting a footnote linking to the GPL or copyleft.org
> or such, to make clear "corresponding source" is a term on its own and
> not just some description, for people that don't already know about
> "corresponding source".
> 
>>> 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---
>>> I don't see how a fancy wording amounting to essentially the same thing would reduce confusion or
>>> avoid latent assumptions.
>> 
>> We have to consider how the audience will be experiencing the documentation. Are they reading it
>> like a novel, tuned in to each step of the process, or are they briefly approaching a paragraph
>> at a time, trying to quickly gather information for how to accomplish what they need so that they
>> can return to their work?
>> 
>> While we should seek to reduce verbosity, which means reducing the inclusion of unnecessary
>> information, we should also be optimizing each paragraph to be self-contained snapshots, lacking
>> ambiguity. I addressed this in my Guix Days talk, and most people seemed to agree with that point.
>> 
>>> To make things more concrete and to resolve conflicts between the principles a few cases have been
>>> worked out:
>> 
>> No "principals" had yet been explicitly addressed.
> 
> Assuming that principals = principles, those principles have already
> been mentioned above -- see the bullet list in 20.4.5. But yes, the
> conflicts have not yet been addressed and aren't anywhere.
> 
>> If I stumble onto this sentence in isolation, I
>> will have have to ask: "What conflicts and principles?". By being explicit, we optimize towards a
>> "snapshot" that can be better understood in isolation.
>> 
>> The term "subjective variation" may be obtuse. I chose it in order to concisely say "... and
>> reducing friction in the review process introduced by several autonomous individuals with
>> distinct programming practices and backgrounds working together on a collective project".
>> 
>> I think it does the work, but others may disagree.
> 
> I do not see how your wording is more explicit than mine.
> 
> While I did not mention what the conflicts were, neither are you
> mentioning (in the text itself) what the "subjective variations" would be.
> 
> I don't think you have to ask "What conflicts", as the more frequent
> cases have been worked out below, resolving the potential conflicts.
> There might be some conflicts remaining, but it's hard to write about
> conflicts of which I don't know that they exist, and if they are known
> to exist, I think it would be better to resolve the conflicts (with a
> few new worked-out cases) and that way remove them from existence.
> 
> I'll have a try at rewording things in the next version to avoid
> implicitness and ambiguity, though I do not expect success.
> 
> Additionally, I don't see why this sentence has to be understood in
> isolation but not the first two sentences ‘Snippets, phases and patches
> at times serve overlapping purposes. To decide between the three, there
> are a few guiding principles:’.
> 
>>> [...]
>>> The purpose of the hypothetical patch or phase is to remove the non-freeness. As such, if the
>>> non-freeness wasn't removed, the patch or phase did not work, for the local meaning of "working".
>>> This is machine-independent (so no "it might work on their machine"), unless there is some kind of
>>> non-determinism, but I haven't ever noticed that happening for non-freeness removal code.
>>> 
>>> 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---
>>> Why the change:
>>> 
>>> * singular->plural (for: patch) -- is this to reduce the wordcount (avoid an 'a'), or for
>>> consistency, or ...?
>>> * passive->active (for: removing -> that removes) -- it becomes more wordy, so seems harder to
>>> follow for me
>> 
>> "Removing" is here a gerund, which shouldn't be applied to objects. This is a grammatical error.
>> The sentences as a whole were adjusted to accommodate the correction.
> 
> I don't know how this form of a verb would be classified in English. I
> don't see why "removing" shouldn't be applied to objects and I don't see
> how it is a grammatical error; that construct parses fine for me. It's a
> bogus construct in my native language but it seems to work well in English.
> 
>>> * appear->be distributed -- more wordy, also things parts of Guix itself (and hence not
>>> distributed, except for "guix build guix" and "guix pull") should be free so I don't think being
>>> more specific makes things more precise.
>> 
>> I'm not attached to using distributed over "appears", it just seems more explicit.
> 
> I'll try looking for a more explicit word that is not too specific.
> 
>>> * "only in its patches" -> "if it only appears within the context of a patch" -- more wordy, and
>>> more indirection
>>> * "For a phases" -> "Concerning phases" -- slightly less direct
>> 
>> We're here discussing a general indefinite case, and thus the plural form is more proper.
> 
> Is "general indefinite case" grammatical terminology or a description?
> For the former: I'm not finding any relevant search results.
> 
> I am not following how you go from "a general indefinite case" to "thus
> the plural it is more proper". A plural seems to be more common in these
> situations and doesn't seem to cause trouble here so I think I'll switch
> to a plural in the next version, but I don't see how it is more proper.
> 
>> [...]
>> 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,
>>> Right, I already introduces a store file name, and that "otherwise" refers to the same store file
>>> name.
>>> 
>>> "the store file name" is singular, so ^W^W -- nevermind, that's a subjunctive? I would go for the
>>> simpler "if the store file name were embedded in the source", dropping the 'to be' indirection.
>> 
>> That sounds good to me.
>> 
>>> Question: do you know how to decide between "if X were to be embedded"/"if X were embedded" and "if
>>> X was embedded"?
>> 
>> 1st case: evokes future anterior; predication is contingent & retroactive. Should be used in
>> indeterminate circumstances.
>> 2nd case: predication is determined by the present. We can know at present whether x is currently
>> embedded.
>> 3rd case: predication is determined by the past. We can know whether x was *ever* embedded.
>> 
>> Why?
> 
> I was wondering if the 2nd case is considered correct grammar (even if
> maybe not appropriate in this particular case) or just a personal quirk.
> Also, when learning English grammar, it was more based on 'feel' than
> explicit rules and consequently it was hard to decide between (2) and (3).
> 
> I don't know about (1), but (3) indeed doesn't seem appropriate here.
> 
> I'll change it to (2) in the next version.
> 
> Greetings,
> Maxime.

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

[Maxime Devos]

[-- Attachment #1.1.1: Type: text/plain, Size: 660 bytes --]

On 10-08-2022 12:33, blake@reproduciblemedia.com wrote:

> None of the edits I made were in criticism. In an academic context a proof reader would mark
> almost all the same sentences for revision.

As far as I'm aware, I do not have implied the contrary anywhere previously.

I do think they are criticism though -- more precisely, constructive 
criticism. There might be a difference in terminology here, e.g. 
according to Wikipedia and its source, some languages make a distinction 
between critique and criticism

To be clear, I consider your criticism to be a good thing, I just happen 
to disagree on some points.

Greetings,
Maxime.


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