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

[blake@reproduciblemedia.com]

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

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

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