From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id SOFXHxZM82KnZQEAbAwnHQ (envelope-from ) for ; Wed, 10 Aug 2022 08:11:34 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id sC5rHxZM82K2KwEA9RJhRA (envelope-from ) for ; Wed, 10 Aug 2022 08:11:34 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 1B952836E for ; Wed, 10 Aug 2022 08:11:34 +0200 (CEST) Received: from localhost ([::1]:54718 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oLewH-0006JZ-5K for larch@yhetil.org; Wed, 10 Aug 2022 02:11:33 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51502) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oLevZ-0006JM-DA for guix-devel@gnu.org; Wed, 10 Aug 2022 02:10:49 -0400 Received: from out0.migadu.com ([2001:41d0:2:267::]:11921) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oLevV-0007D9-Vf for guix-devel@gnu.org; Wed, 10 Aug 2022 02:10:49 -0400 MIME-Version: 1.0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=reproduciblemedia.com; s=key1; t=1660111841; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=O1b3daSXQVULF+Gur63oSeUl47vdMeBzuZUFZNi0PGA=; b=RD3sV1UR1ivu9hQ/SZkTjTwvn2VFs5KQ+dtfJGUFJksc7G5s2sPX34aNbjDJpXcfdIMz4e gQggx/t+R9XY/p63FAfqcSR2fDDa6vnyxVHzOBtYAWfKJqbscTbl0JSPR+XWZ1k8S3rdYX GZCa8Rdm8lWkig8UtlJhlLJsvBcAMbY= Date: Wed, 10 Aug 2022 06:10:41 +0000 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. From: blake@reproduciblemedia.com Message-ID: Subject: Re: v2: A proposal of a consistent set of clear rules and guidelines involving snippets, phases and patches. To: "Maxime Devos" , "Guix-devel" In-Reply-To: <3dfad2da-9b2f-8615-8ad0-fa42dfd6cb79@telenet.be> References: <3dfad2da-9b2f-8615-8ad0-fa42dfd6cb79@telenet.be> <98da36a2-d0cc-77da-77bf-6984253131ac@telenet.be> <5948e681e5939058f699c0aa8f4f7c52@reproduciblemedia.com> Received-SPF: pass client-ip=2001:41d0:2:267::; envelope-from=blake@reproduciblemedia.com; helo=out0.migadu.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: guix-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: "Guix-devel" X-Migadu-Flow: FLOW_IN X-Migadu-To: larch@yhetil.org X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1660111894; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=O1b3daSXQVULF+Gur63oSeUl47vdMeBzuZUFZNi0PGA=; b=BnsJ/FT8c0WC87RXM6OrypUA5xeY60nk5uZoxGRbV7/qDxRRmy/17Zr79Dj5WRgNCzKAqc whQQGVjeCVU+R8OYerdGwG3jhjochsKheqc1OxgQecGPcUBnUlw1+fgcMtcqYNzgrS62E4 xGTe1EcVTbu7JjZ/LJ5V/zTDOZhTQl30KfMAhHktyEJuNAFqj8Ht1YLZmVJ8O0QdfYdb3D e46h12bVG7evCEAqxP9jOSfWJXnfmMi+d7Hht60KqxByPpe0NOA6tvBC9y0sUMcIzElemL qMz5rXV0kEMtE4N3jCmSrXssWQcpPtbGjtjBFltaYOP78aWv/+YutUbsmwDJzQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1660111894; a=rsa-sha256; cv=none; b=mvfpC23+ekFmt7HK2wsY9hzVVizLndOtp7SJZoiCL3ETk/sLillEAY7cVWM2YJwHAGeaOq LKJh/a2C7SDd8okHw1Ct67EwaBvyjnQRGzPLUEcTmktD4JHqjitpFdYGJgBlP4iskwixjW 8OQ6ugZU/faAJP5clD68jCewkbBVAneyjwTg9OPhxqKcQqS2ybK9rACkpwZI+YGkBqgQo4 y+JLjBqlPfT4kyzI/36Zb889h+1hJMLjuFc6fuzXcBz2gedCSH51Na19ffTSTv3lGlZbsN aQTPHCYks4X5u1116t7mFd8uTLSS830lHczoaDOAy2Nc4LvxlIbFzegDfGcr2w== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=reproduciblemedia.com header.s=key1 header.b=RD3sV1UR; dmarc=pass (policy=quarantine) header.from=reproduciblemedia.com; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -3.89 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=reproduciblemedia.com header.s=key1 header.b=RD3sV1UR; dmarc=pass (policy=quarantine) header.from=reproduciblemedia.com; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 1B952836E X-Spam-Score: -3.89 X-Migadu-Scanner: scn1.migadu.com X-TUID: /dQ87aY96vpQ Hi Maxime,=0A=0AAugust 9, 2022 4:30 PM, "Maxime Devos" wrote:=0A=0A> On 05-08-2022 18:59, blake@reproduciblemedia.com wro= te:=0A> =0A>> Hi Maxime,=0A>> Adding some basic grammatical corrections b= elow:=0A> =0A> I have read several proposed corrections, but most of them= don't appear to be grammatical=0A> corrections but rather stylistic or a= bout (non-grammar) clarity or contents.=0A=0AYes, there are stylistic sug= gestions as well -- well-formed writing isn't merely a matter of=0Agramma= r, but also stylistic consistency. But thats not to say style is merely a= subjective=0Amatter of preference; this is based on years as a philosoph= y PhD reviewing students and=0Acolleagues' papers, which requires that on= e becomes intimate with all of the major style guides=0Athat set the stan= dard rules for editing the English language.=0A=0AIf I just said "making = some basic grammatical edits", its because I was reading the email,=0Area= lized many improvements could be added and wanted to get through it quick= so that I could=0Ahave time for it in the first place. Just trying to he= lp with something I'm quite skilled in.=0A=0A>> August 5, 2022 1:59 PM, "= Maxime Devos" wrote:=0A>> Technical grammatical = correction: the software that Guix "has" is that in the monorepo,=0A>> bu= t it "distributes" many packages. Thus:=0A>> --8<---------------cut here-= --------------start------------->8---=0A>> * In principle, Guix only dist= ributes free software; when the upstream source contains some=0A>> non-fr= ee software, it should be removed such that =E2=80=98guix build --source= =E2=80=99 returns the "freed"=0A>> source code rather than the unmodified= upstream source (see: 28.4.1 Software Freedom).=0A>> --8<---------------= cut here---------------end--------------->8---=0A> =0A> I consider the di= fference between referring to external source code by including a=0A> (sn= ippet-sanitised) copy or downloading it from an URL + snippet-sanitising = to be immaterial,=0A> except for space and I/O savings, so I consider "ha= s" to include "distributes".=0A> =0A> While "distributes" is more specifi= c, I really meant "has" here -- gnu/packages/patches/... and=0A> gnu/pack= ages/*.scm must be free too, even if it is was not a distributed package = (more concretely,=0A> see the bits about patches failing to remove non-fr= eeness).=0A> =0A> [...]=0A=0AThis is simply a grammatical error. "Has" is= third person singular. While its common to speak=0Ain such a way, it's n= ot proper English, and including minor slang should be avoided in technic= al=0Awriting. Otherwise inconsistency of presentation is guaranteed, caus= ing serious overhead for=0Areaders.=0A=0A>> =0A> =0A> * The source of the= package needs to correspond to what is actually built (i.e., act as the= =0A> corresponding source), to fulfill our ethical and legal obligations.= =0A>> The [i.e.] addendum above is redundant, its better worded as:=0A>> = --8<---------------cut here---------------start------------->8---=0A>> * = The source of a package must correspond to what is actually built (i.e., = there must be=0A>> an explicit relation between source code and the resul= t of its build for all builds),=0A>> to fulfill our ethical and legal obl= igations.=0A>> --8<---------------cut here---------------end-------------= -->8---=0A> =0A> You write that the addendum is redundant, but then chang= e the addendum by replacing a word in the=0A> addendum by a possible defi= nition. I'm not following how that reduces redundancy, and it also=0A> ap= pears to be contrary to the lack of verbosity that Andreas would like.=0A= =0ARedundancy in language is information expressed more than once. Includ= ing redundant clauses=0Ais bad grammar[1]=0A=0AYou wrote:=0A> The source = of the package needs to correspond to what is actually built (i.e., act a= s the=0A> corresponding source)=0A=0AYou simply said the same thing twice= . It is by definition, a redundant clause.=0A=0A> then change the addendu= m by replacing a word in the=0A> addendum by a possible definition.=0A=0A= Elaboration doesnt necessarily add redunancy, it is useful for clarifying= statements. I was=0Atrying to infer your intention in adding the clause,= to offer an example of how it could be=0Amore clearly stated.=0A=0A[1] h= ttps://en.wikipedia.org/wiki/Redundancy_(linguistics)=0A=0A> * It is conv= enient for the source derived from an origin to build on any system that = the upstream=0A> package supports.=0A> * The source needs to actually wor= k, not only on your Guix system but also for other systems; this=0A> requ= ires some care for substitutions involving store items and other architec= ture-specific changes.=0A> * Sometimes, there is more than one way to do = it. Let's go for the simplest one. Sometimes, which=0A> tool is the simpl= est, is subjective, that's fine too.=0A>> I think would be more clearly w= orded as:=0A>> --8<---------------cut here---------------start-----------= -->8---=0A>> * When presented with a variety of strategies for defining a= package, choose whichever is simplest.=0A>> Sometimes this is subjective= , which is also fine. What matters is that you prefer techniques that=0A>= > are common within the community (i.e. patterns that appear throughout g= nu/packages/...) and=0A>> are thus clearly legible for reviewers.=0A>> --= 8<---------------cut here---------------end--------------->8---=0A> =0A> = To be clear, this is to replace the third point (Sometimes, there's more = than one way to do it,=0A> etc.), without removing the previous two?=0A= =0AOnly for the third point.=0A=0A> I would not use combinations like 'pr= esented with a variety of strategies' however, I don't think=0A> that lea= ds to clarity. Also, the preferences of 'you' are not all that important = here, it's what=0A> they choose for that's important even if it is not th= eir preference. (Though the two coinciding=0A> would be ideal of course!)= Maybe:=0A> =0A> When there is more than one way to do something, choose = whichever method is the simplest.=0A> Sometimes this is subjective, which= is also fine. What matters is that you use techniques that=0A> are commo= n within the community (i.e. patterns that appear throughout gnu/packages= /...) and=0A> are thus clearly legible for reviewers.=0A=0AYeah thats gre= at.=0A=0A> To make things more concrete and to resolve conflicts between = the principles, a few cases have been=0A> worked out:=0A>> To a newcomer = (the target audience), the above may lead to confusion as to what wasn't = already=0A>> concrete in the above descriptions, or what principles above= come into conflict. There is a mild,=0A>> latent assumption that they ar= e familiar with the Guix workflow, which should be avoided. Thus I=0A>> s= uggest:=0A>> --8<---------------cut here---------------start-------------= >8---=0A>> For the purpose of clarifying preferred practices and reducing= friction in the review process=0A>> introduced by subjective variation, = a few guidelines have been worked out:=0A>> --8<---------------cut here--= -------------end--------------->8---=0A> =0A> I don't see how a fancy wor= ding amounting to essentially the same thing would reduce confusion or=0A= > avoid latent assumptions.=0A=0AWe have to consider how the audience wil= l be experiencing the documentation. Are they reading it=0Alike a novel, = tuned in to each step of the process, or are they briefly approaching a p= aragraph=0Aat a time, trying to quickly gather information for how to acc= omplish what they need so that they=0Acan return to their work?=0A=0AWhil= e we should seek to reduce verbosity, which means reducing the inclusion = of unnecessary=0Ainformation, we should also be optimizing each paragraph= to be self-contained snapshots, lacking=0Aambiguity. I addressed this in= my Guix Days talk, and most people seemed to agree with that point.=0A= =0A> To make things more concrete and to resolve conflicts between the pr= inciples a few cases have been=0A> worked out:=0A=0ANo "principals" had y= et been explicitly addressed. If I stumble onto this sentence in isolatio= n, I=0Awill have have to ask: "What conflicts and principles?". By being = explicit, we optimize towards a=0A"snapshot" that can be better understoo= d in isolation.=0A=0AThe term "subjective variation" may be obtuse. I cho= se it in order to concisely say "... and=0Areducing friction in the revie= w process introduced by several autonomous individuals with=0Adistinct pr= ogramming practices and backgrounds working together on a collective proj= ect".=0A=0AI think it does the work, but others may disagree.=0A=0A> Anyw= ay, I'm not seeing any assumption=20that they are already familiar with t= he Guix workflow -- the=0A> point of such sections is to explain the work= flow, people already familiar aren't expected to read=0A> it (at least, n= ot often). I don't see how it would lead to confusion, because it doesn't= allude to=0A> any principles in particular, because the text isn't some = kind of analysis on principles and their=0A> interactions but a howto of = sorts, and because it points to the cases below.=0A=0AIts simply a matter= of ambiguity vs. explication. I think we should choose more explicit wor= ding=0Awhere possible. I can't count the number of times I have had to re= ad an entire article in the=0Adocumentation just so that I could understa= nd a later paragraph's latent assumption that I was=0Areading in a linear= manner.=0A=0A> 20.4.5.1 Removing non-free software. Non-free software ha= s to be removed in a snippet; the reason=0A> is=0A> that a patch or phase= will not work.=0A>> Well, it might work on their machine, but not for co= mmunity standards. To reduce confusion:=0A>> --8<---------------cut here-= --------------start------------->8---=0A>> 20.4.5.1 Removing non-free sof= tware.=0A>> Non-free software should be removed using snippets; when remo= ving non-free software, a patch or=0A>> phase=0A>> will not be accepted.= =0A>> --8<---------------cut here---------------end--------------->8---= =0A> =0A> The purpose of the hypothetical patch or phase is to remove the= non-freeness. As such, if the=0A> non-freeness wasn't removed, the patch= or phase did not work, for the local meaning of "working".=0A> This is m= achine-independent (so no "it might work on their machine"), unless there= is some kind of=0A> non-determinism, but I haven't ever noticed that hap= pening for non-freeness removal code.=0A> =0A> For a patch, the problem i= s that a patch removing a non-free file automatically contains the=0A> no= n-free file (^), and we do not want anything non-free to appear in Guix e= ven if only in its=0A> patches.=0A>> Is better as:=0A>> --8<-------------= --cut here---------------start------------->8---=0A>> For patches, the is= sue is that a patch that removes a non-free file automatically contains t= he=0A>> non-free file (^), and we do not want any non-free software to be= distributed with Guix, even=0A>> if it only appears within the context o= f a patch.=0A>> Concerning phases, the problem is that they do not influe= nce the result of =E2=80=98guix build --source=E2=80=99.=0A>> --8<-------= --------cut here---------------end--------------->8---=0A> =0A> Why the c= hange:=0A> =0A> * singular->plural (for: patch) -- is this to reduce the = wordcount (avoid an 'a'), or for=0A> consistency, or ...?=0A> * passive->= active (for: removing -> that removes) -- it becomes more wordy, so seems= harder to=0A> follow for me=0A=0A"Removing" is here a gerund, which shou= ldn't be applied to objects. This is a grammatical error.=0AThe sentences= as a whole were adjusted to accommodate the correction.=0A=0A> * appear-= >be distributed -- more wordy, also things parts of Guix itself (and henc= e not=0A> distributed, except for "guix build guix" and "guix pull") shou= ld be free so I don't think being=0A> more specific makes things more pre= cise.=0A=0AI'm not attached to using distributed over "appears", it just = seems more explicit.=0A=0A> * "only in its patches" -> "if it only appear= s within the context of a patch" -- more wordy, and=0A> more indirection= =0A> * "For a phases" -> "Concerning phases" -- slightly less direct=0A= =0AWe're here discussing a general indefinite case, and thus the plural f= orm is more proper.=0A=0A> 20.4.5.2 Removing bundled libraries.=0A> Bundl= ed libraries should not be removed with a patch, because then the patch w= ould contain the full=0A> bundled library, which can be large. They can b= e removed either in a snippet or a phase, often=0A> using the procedure '= delete-file-recursively'. There are a few benefits for snippets here:=0A>= When using snippets, the bundled library does not occur in the source re= turned by =E2=80=98guix build=0A> --source=E2=80=99, so users and reviewe= rs do not have to worry about whether the bundled library contains=0A> ma= lware, whether it is non-free, if it contains pre-compiled binaries ... T= here are also less=0A> licensing concerns: if the bundled libraries are r= emoved, it becomes less likely that the licensing=0A> conditions apply to= people sharing the source returned by =E2=80=98guix build --source=E2=80= =99, especially if the=0A> bundled library is not actually used on Guix s= ystems. (*)=0A> As such, snippets are recommended here.=0A> (*) This is _= not_ a claim that you can simply ignore the licenses of libraries when th= ey are=0A> unbundled and replaced by Guix packages -- there are less conc= erns, not none.=0A> 20.4.5.3 Fixing technical issues (compilation errors,= test failures, other bugs ...)=0A> Usually, a bug fix comes in the form = of a patch copied from upstream or another distribution. In=0A> that case= , simply adding the patch to the 'patches' field is the most convenient a= nd usually does=0A> not cause any problems; there is no need to rewrite i= t as a snippet or a phase.=0A> If no ready-made patch already exists, the= n choosing between a patch or a snippet is a matter of=0A> convenience. H= owever, there are two things to keep in mind:=0A> First, when the fix is = not Guix-specific, it is strongly desired to upstream the fix to avoid th= e=0A> additional maintenance cost to Guix. As upstreams cannot accept a s= nippet, writing a patch can be a=0A> more efficient use of time. Secondly= , if the fix of a technical issue embeds a store file name,=0A> then it h= as to be a phase. Otherwise, if a store file name was embedded in the sou= rce, the result=0A> of 'guix build --source' would be unusable on non-Gui= x systems and likely also unusable on Guix=0A> systems of another archite= cture.=0A>> And some basic last corrections here:=0A>> --8<--------------= -cut here---------------start------------->8---=0A>> First, when the fix = is not Guix-specific, it is strongly desired by upstream that the fix avo= ids=0A>> any additional maintenance costs for Guix.=0A> =0A> While I woul= d like upstreams to care about additional maintenance costs downstream, I= do not think=0A> we have proof of that at the moment, so I would stick w= ith the meaning of the original sentence --=0A> I used 'upstream' as a ve= rb here, not as a noun.=0A> =0A> However, I could look into reformulating= the sentence a bit to avoid reading it as a noun and hence=0A> avoid bac= ktracing when parsing that sentence?=0A=0AYeah I'd agree that would be mo= re clear.=0A=0A>> As upstream cannot accept a snippet, writing a patch ca= n be a=0A> =0A> There's more than one upstream as Guix has multiple packa= ges, so the plural "upstreams" seems more=0A> correct to me, though I wou= ldn't consider the singular to be incorrect. I have however, in some=0A> = other places used singular for something of which there exist multiple in= stances, so I'll look at=0A> making the wording consistent one way or the= other.=0A>> more efficient use of time. Secondly, if the fix of a techni= cal issue embeds a store file name,=0A>> then it has to be a phase. Other= wise, if the store file name were to be embedded in the source,=0A> =0A> = Right, I already introduces a store file name, and that "otherwise" refer= s to the same store file=0A> name.=0A> =0A> "the store file name" is sing= ular, so ^W^W -- nevermind, that's a subjunctive? I would go for the=0A> = simpler "if the store file name were embedded in the source", dropping th= e 'to be' indirection.=0A=0AThat sounds good to me.=0A=0A> Question: do y= ou know how to decide between "if X were to be embedded"/"if X were embed= ded" and "if=0A> X was embedded"?=0A=0A1st case: evokes future anterior; = predication is contingent & retroactive. Should be used in=0Aindeterminat= e circumstances.=0A2nd case: predication is determined by the present. We= can know at present whether x is currently=0Aembedded.=0A3rd case: predi= cation is determined by the past. We can know whether x was *ever* embedd= ed.=0A=0AWhy?=0A=0A>> the=0A>> result of 'guix build --source' would be u= nusable on non-Guix systems, and also likely unusable on=0A>> Guix system= s of another architecture.=0A>> --8<---------------cut here--------------= -end--------------->8---=0A> =0A> The Oxford comma or lack thereof are ac= ceptable stylistic conventions, but not a grammatical error.=0A> There ar= e only two conjucts here though, so I don't think the Oxford comma applie= s here.=0A> Additionally, the two conjucts are about mostly the same=20th= ing, but just different (similar!)=0A> subcases that merely happen to nee= d different qualifications (unusable on non-Guix vs. likely=0A> unusable = on different-arch Guix), so I don't think that 'also' brings something he= re.=0A> =0A> Greetings,=0A> Maxime.