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

[Maxime Devos]

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.



OpenPGP_0x49E3EE22191725EE.asc
Description: OpenPGP public key


OpenPGP_signature
Description: OpenPGP digital signature

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]

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.



OpenPGP_0x49E3EE22191725EE.asc
Description: OpenPGP public key


OpenPGP_signature
Description: OpenPGP digital signature

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

[Maxime Devos]

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.



OpenPGP_0x49E3EE22191725EE.asc
Description: OpenPGP public key


OpenPGP_signature
Description: OpenPGP digital signature

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.

[Maxime Devos]

On 10-08-2022 12:33, bl...@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.



OpenPGP_0x49E3EE22191725EE.asc
Description: OpenPGP public key


OpenPGP_signature
Description: OpenPGP digital signature

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"  wrote:

> On 10-08-2022 08:10, bl...@reproduciblemedia.com wrote:
> 
>> August 5, 2022 1:59 PM, "Maxime Devos"  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 abou

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

[Maxime Devos]

On 10-08-2022 08:10, bl...@reproduciblemedia.com wrote:

August 5, 2022 1:59 PM, "Maxime Devos"  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--

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"  wrote:

> On 05-08-2022 18:59, bl...@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"  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. patter

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

[Maxime Devos]

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


OpenPGP_0x49E3EE22191725EE.asc
Description: OpenPGP public key


OpenPGP_signature
Description: OpenPGP digital signature

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.

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

On 05-08-2022 18:59, bl...@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"  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 sect

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

[Maxime Devos]

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.



OpenPGP_0x49E3EE22191725EE.asc
Description: OpenPGP public key


OpenPGP_signature
Description: OpenPGP digital signature

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.

[blake]

Hi Maxime,

Adding some basic grammatical corrections below:

August 5, 2022 1:59 PM, "Maxime Devos"  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 rem

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

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


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

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

[Maxime Devos]

Currently writing a v2 with a structure like Julien proposed.

Greetings,
Maxime.



OpenPGP_0x49E3EE22191725EE.asc
Description: OpenPGP public key


OpenPGP_signature
Description: OpenPGP digital signature

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

[Maxime Devos]

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.



OpenPGP_0x49E3EE22191725EE.asc
Description: OpenPGP public key


OpenPGP_signature
Description: OpenPGP digital signature

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

[Maxime Devos]

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.



OpenPGP_0x49E3EE22191725EE.asc
Description: OpenPGP public key


OpenPGP_signature
Description: OpenPGP digital signature

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.

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

[Ludovic Courtès]

Hello!

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

[Julien Lepiller]

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

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

[Maxime Devos]

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.


OpenPGP_0x49E3EE22191725EE.asc
Description: OpenPGP public key


OpenPGP_signature
Description: OpenPGP digital signature

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

[Julien Lepiller]

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

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

[Maxime Devos]

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

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

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


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

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


[start]

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


20.4.5 Snippets, phases and patches

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


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

   @c this relaxes the old rule a little

 * Ideally, the source derived from the origin should be usable for
   building on any system that the upstream package supports (even if
   Guix does not support that system), as a courtesy to the people that
   the source code is shared with. However, this is not an absolute
   rule, most important is that it is usable on Guix and it is allowed
   to neglect