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

[Maxime Devos <maximedevos@telenet.be>]

[-- Attachment #1.1.1: 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 --]