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

[blake@reproduciblemedia.com]

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.