From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id YFcfM2GL82JNIAAAbAwnHQ (envelope-from ) for ; Wed, 10 Aug 2022 12:41:37 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id 0LUoM2GL82LRdgEA9RJhRA (envelope-from ) for ; Wed, 10 Aug 2022 12:41:37 +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 5EC2421CAC for ; Wed, 10 Aug 2022 12:41:37 +0200 (CEST) Received: from localhost ([::1]:41732 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oLj9c-0000Pl-9U for larch@yhetil.org; Wed, 10 Aug 2022 06:41:36 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40652) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oLj1x-0004x0-70 for guix-devel@gnu.org; Wed, 10 Aug 2022 06:33:42 -0400 Received: from out1.migadu.com ([91.121.223.63]:54621) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oLj1s-0005eJ-Eq for guix-devel@gnu.org; Wed, 10 Aug 2022 06:33:40 -0400 MIME-Version: 1.0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=reproduciblemedia.com; s=key1; t=1660127612; 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=bnVOnpyQ2/+uJDdwuYVtJtcrrQ0LYECVpggsy54TVa8=; b=Te2orvG6LNCdfGYxg6voCz1RFyD7APAmtJrQas6idQhmK3FKEvHRN0Z4S3VXq5JUN0t01K il7jub4HDrr50aC/6DsbzyDq2EyTgZkDuDtbQDBrUOrqz4r3CBPclRh554AMybBuuOXoT1 rKI+BSms7Lq/ANekxRSaRj7Pu2cKDlo= Date: Wed, 10 Aug 2022 10:33:32 +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: <872bd3c4-956d-28fd-2608-1e546f76f334@telenet.be> References: <872bd3c4-956d-28fd-2608-1e546f76f334@telenet.be> <3dfad2da-9b2f-8615-8ad0-fa42dfd6cb79@telenet.be> <98da36a2-d0cc-77da-77bf-6984253131ac@telenet.be> <5948e681e5939058f699c0aa8f4f7c52@reproduciblemedia.com> Received-SPF: pass client-ip=91.121.223.63; envelope-from=blake@reproduciblemedia.com; helo=out1.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=1660128097; 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=bnVOnpyQ2/+uJDdwuYVtJtcrrQ0LYECVpggsy54TVa8=; b=U879Ue07Gmk5D0E1n1xUHbBVIqxY9Q6eavaq3rMZvBAG4iQZVGWScmNpqYlv+ahMgXlSSS 6srtODMAhymzD8oofgDoCWaFhTi3luJEaoJUybOh1wH368NCzEjlJFSb+GzloibqQHybrF i3saUzxeGbwzppbHjsUWXu8g333Dgx1HvHm9aWJOcQKnmDZdJH+R3+aclJOqb+ujiqJ2xZ ktwoBORrM8dGBXcUSre1q6R3xI5z3a7hE19ZRnSFxffLbQS/AHNCSjcLSRRNVOS/khGR18 RmhB8zzMJWiGo8sjAIUiPZ8rWc4zhyRMknykyxQdNdL9zlX+qjmmQ5FdsmqDvg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1660128097; a=rsa-sha256; cv=none; b=Obcupu8OkUIaarp4oGuGsY1GDymBdATvZrB7buF0ddgXPk2NdWOBAOPE3lU++SQrFaawVh HkbRnkSo9d0t1ITcgRRGfP6jvSCB26BWFtLNnIphxCkESjUprZ2Wnski83x21KB3drPpt0 TS5ObjW/nXj2vYBUzM0XDMcqFgjMVbEK3NIicUe8HTrsSPoQ0QMxhDR/CxR3hm/XeMb9k2 +sXjxCU+fX/T72XYDF7VPFBEPl7d9OY1+BrMbzbf7OwEGP9Z/RxRTygR4uRmPa9it40020 lSoM181GRMh0mtN8HCZAgUKbrV/bKmZyqYP9EJRrN61I/GJ2bwqRzJtxt29jRg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=reproduciblemedia.com header.s=key1 header.b=Te2orvG6; 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: -5.69 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=reproduciblemedia.com header.s=key1 header.b=Te2orvG6; 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: 5EC2421CAC X-Spam-Score: -5.69 X-Migadu-Scanner: scn0.migadu.com X-TUID: 5HQPs4Lzel4x None of the edits I made were in criticism. In an academic context a proo= f reader would mark=0Aalmost all the same sentences for revision.=0A=0AAu= gust 10, 2022 9:06 AM, "Maxime Devos" wrote:=0A= =0A> On 10-08-2022 08:10, blake@reproduciblemedia.com wrote:=0A> =0A>> Au= gust 5, 2022 1:59 PM, "Maxime Devos" wrote:=0A>>= Technical grammatical correction: the software that Guix "has" is that i= n the monorepo,=0A>> but it "distributes" many packages. Thus:=0A>> --8<-= --------------cut here---------------start------------->8---=0A>> * In pr= inciple, Guix only distributes free software; when the upstream source co= ntains some=0A>> non-free software, it should be removed such that =E2=80= =98guix build --source=E2=80=99 returns the "freed"=0A>> source code rath= er than the unmodified upstream source (see: 28.4.1 Software Freedom).=0A= >> --8<---------------cut here---------------end--------------->8---=0A>>= > I consider the difference between referring to external source code by = including a=0A>>> (snippet-sanitised) copy or downloading it from an URL = + snippet-sanitising to be immaterial,=0A>>> except for space and I/O sav= ings, so I consider "has" to include "distributes".=0A>>> =0A>>> While "d= istributes" is more specific, I really meant "has" here -- gnu/packages/p= atches/... and=0A>>> gnu/packages/*.scm must be free too, even if it is w= as not a distributed package (more concretely,=0A>>> see the bits about p= atches failing to remove non-freeness).=0A>>> =0A>>> [...]=0A>> =0A>> Thi= s is simply a grammatical error. "Has" is third person singular. While it= s common to speak=0A>> in such a way, it's not proper English, and includ= ing minor slang should be avoided in technical=0A>> writing. Otherwise in= consistency of presentation is guaranteed, causing serious overhead for= =0A>> readers.=0A> =0A> "Has" is third person singular, and "Guix" is sin= gular and not "I" or=0A> "you", so "has" seems appropriate here to me.=0A= > =0A> I think that matching the singular/plural of the verb and the subj= ect is=0A> common, standard and proper English and not slang.=0A> =0A> Go= ing by previous replies, you seem to know English well, so I think=0A> th= ere's some miscommunication here.=0A> =0A> (Even better would be to repla= ce the rather generic =E2=80=98to have=E2=80=99 by=0A> something more spe= cific, but I'll have to think a bit about what would=0A> be more specific= yet not overly specific.)=0A> =0A>>> * The source of the package needs t= o correspond to what is actually built (i.e., act as the=0A>>> correspond= ing source), to fulfill our ethical and legal obligations.=0A>> =0A>> The= [i.e.] addendum above is redundant, its better worded as:=0A>> --8<-----= ----------cut here---------------start------------->8---=0A>> * The sourc= e of a package must correspond to what is actually built (i.e., there mus= t be=0A>> an explicit relation between source code and the result of its = build for all builds),=0A>> to fulfill our ethical and legal obligations.= =0A>> --8<---------------cut here---------------end--------------->8---= =0A>>> You write that the addendum is redundant, but then change the adde= ndum by replacing a word in the=0A>>> addendum by a possible definition. = I'm not following how that reduces redundancy, and it also=0A>>> appears = to be contrary to the lack of verbosity that Andreas would like.=0A>> =0A= >> Redundancy in language is information expressed more than once. Includ= ing redundant clauses=0A>> is bad grammar[1]=0A>> =0A>> You wrote:=0A>>> = The source of the package needs to correspond to what is actually built (= i.e., act as the=0A>>> corresponding source)=0A>> =0A>> You simply said t= he same thing twice. It is by definition, a redundant clause.=0A>> =0A>>>= then change the addendum by replacing a word in the=0A>>> addendum by a = possible definition.=0A>> =0A>> Elaboration doesnt necessarily add reduna= ncy, it is useful for clarifying statements. I was=0A>> trying to infer y= our intention in adding the clause, to offer an example of how it could b= e=0A>> more clearly stated.=0A>> =0A>> [1] https://en.wikipedia.org/wiki/= Redundancy_(linguistics)=0A> =0A> The purpose of 'i.e.' constructs is to = state the same thing differently,=0A> to clarify matters (by elaboration = or by redundancy). I don't see how=0A> redundancy is bad, though it can e= asily be overdone.=0A> =0A> I think that explicitly mentioning the term '= corresponding source'=0A> instead of only the more implicit 'source of X = corresponds to Y',=0A> because the former 'corresponding source' has a ve= ry specific meaning=0A> (*) in free software, whereas the latter construc= t is more ambiguous.=0A> =0A> Compare with your definition 'there must be= an explicit relation ...=E2=80=99,=0A> which loses a lot of nuance.=0A> = =0A> (*) E.g., the GPL has a long and detailed definition: =E2=80=98The= =0A> "Corresponding Source" for a work in object code form means all the= =0A> source code needed to generate, install, [lots and lots of text]=E2= =80=99.=0A> =0A> I can look into inserting a footnote linking to the GPL = or copyleft.org=0A> or such, to make clear "corresponding source" is a te= rm on its own and=0A> not just some description, for people that don't al= ready know about=0A> "corresponding source".=0A> =0A>>> To make things mo= re concrete and to resolve conflicts between the principles, a few cases = have been=0A>>> worked out:=0A>> =0A>> To a newcomer (the target audience= ), the above may lead to confusion as to what wasn't already=0A>> concret= e in the above descriptions, or what principles above come into conflict.= There is a mild,=0A>> latent assumption that they are familiar with the = Guix workflow, which should be avoided. Thus I=0A>> suggest:=0A>> --8<---= ------------cut here---------------start------------->8---=0A>> For the p= urpose of clarifying preferred practices and reducing friction in the rev= iew process=0A>> introduced by subjective variation, a few guidelines hav= e been worked out:=0A>> --8<---------------cut here---------------end----= ----------->8---=0A>>> I don't see how a fancy wording amounting to essen= tially the same thing would reduce confusion or=0A>>> avoid latent assump= tions.=0A>> =0A>> We have to consider how the audience will be experienci= ng the documentation. Are they reading it=0A>> like a novel, tuned in to = each step of the process, or are they briefly approaching a paragraph=0A>= > at a time, trying to quickly gather information for how to accomplish w= hat they need so that they=0A>> can return to their work?=0A>> =0A>> Whil= e we should seek to reduce verbosity, which means reducing the inclusion = of unnecessary=0A>> information, we should also be optimizing each paragr= aph to be self-contained snapshots, lacking=0A>> ambiguity. I addressed t= his 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 betwe= en the principles a few cases have been=0A>>> worked out:=0A>> =0A>> No "= principals" had yet been explicitly addressed.=0A> =0A> Assuming that pri= ncipals =3D principles, those principles have already=0A> been mentioned = above -- see the bullet list in 20.4.5. But yes, the=0A> conflicts have n= ot yet been addressed and aren't anywhere.=0A> =0A>> If I stumble onto th= is sentence in isolation, I=0A>> will have have to ask: "What conflicts a= nd principles?". By being explicit, we optimize towards a=0A>> "snapshot"= that can be better understood in isolation.=0A>> =0A>> The term "subject= ive variation" may be obtuse. I chose it in order to concisely say "... a= nd=0A>> reducing friction in the review process introduced by several aut= onomous individuals with=0A>> distinct programming practices and backgrou= nds working together on a collective project".=0A>> =0A>> I think it does= the work, but others may disagree.=0A> =0A> I do not see how your wordin= g is more explicit than mine.=0A> =0A> While I did not mention what the c= onflicts were, neither are you=0A> mentioning (in the text itself) what t= he "subjective variations" would be.=0A> =0A> I don't think you have to a= sk "What conflicts", as the more frequent=0A> cases have been worked out = below, resolving the potential conflicts.=0A> There might be some conflic= ts remaining, but it's hard to write about=0A> conflicts of which I don't= know that they exist, and if they are known=0A> to exist, I think it wou= ld be better to resolve the conflicts (with a=0A> few new worked-out case= s) and that way remove them from existence.=0A> =0A> I'll have a try at r= ewording things in the next version to avoid=0A> implicitness and ambigui= ty,=20though I do not expect success.=0A> =0A> Additionally, I don't see = why this sentence has to be understood in=0A> isolation but not the first= two sentences =E2=80=98Snippets, phases and patches=0A> at times serve o= verlapping purposes. To decide between the three, there=0A> are a few gui= ding principles:=E2=80=99.=0A> =0A>>> [...]=0A>>> The purpose of the hypo= thetical 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 machine-independent (so no "it= might work on their machine"), unless there is some kind of=0A>>> non-de= terminism, but I haven't ever noticed that happening for non-freeness rem= oval code.=0A>>> =0A>>> For a patch, the problem is that a patch removing= a non-free file automatically contains the=0A>>> non-free file (^), and = we do not want anything non-free to appear in Guix even if only in its=0A= >>> patches.=0A>> =0A>> Is better as:=0A>> --8<---------------cut here---= ------------start------------->8---=0A>> For patches, the issue is that a= patch that removes a non-free file automatically contains the=0A>> non-f= ree file (^), and we do not want any non-free software to be distributed = with Guix, even=0A>> if it only appears within the context of a patch.=0A= >> Concerning phases, the problem is that they do not influence the resul= t of =E2=80=98guix build --source=E2=80=99.=0A>> --8<---------------cut h= ere---------------end--------------->8---=0A>>> Why the change:=0A>>> =0A= >>> * singular->plural (for: patch) -- is this to reduce the wordcount (a= void 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.=0A>> The senten= ces as a whole were adjusted to accommodate the correction.=0A> =0A> I do= n't know how this form of a verb would be classified in English. I=0A> do= n't see why "removing" shouldn't be applied to objects and I don't see=0A= > how it is a grammatical error; that construct parses fine for me. It's = a=0A> bogus construct in my native language but it seems to work well in = English.=0A> =0A>>> * appear->be distributed -- more wordy, also things p= arts of Guix itself (and hence not=0A>>> distributed, except for "guix bu= ild guix" and "guix pull") should be free so I don't think being=0A>>> mo= re specific makes things more precise.=0A>> =0A>> I'm not attached to usi= ng distributed over "appears", it just seems more explicit.=0A> =0A> I'll= try looking for a more explicit word that is not too specific.=0A> =0A>>= > * "only in its patches" -> "if it only appears within the context of a = patch" -- more wordy, and=0A>>> more indirection=0A>>> * "For a phases" -= > "Concerning phases" -- slightly less direct=0A>> =0A>> We're here discu= ssing a general indefinite case, and thus the plural form is more proper.= =0A> =0A> Is "general indefinite case" grammatical terminology or a descr= iption?=0A> For the former: I'm not finding any relevant search results.= =0A> =0A> I am not following how you go from "a general indefinite case" = to "thus=0A> the plural it is more proper". A plural seems to be more com= mon in these=0A> situations and doesn't seem to cause trouble here so I t= hink I'll switch=0A> to a plural in the next version, but I don't see how= it is more proper.=0A> =0A>> [...]=0A>> more efficient use of time. Seco= ndly, if the fix of a technical issue embeds a store file name,=0A>> then= it has to be a phase. Otherwise, if the store file name were to be embed= ded in the source,=0A>>> Right, I already introduces a store file name, a= nd that "otherwise" refers to the same store file=0A>>> name.=0A>>> =0A>>= > "the store file name" is singular, so ^W^W -- nevermind, that's a subju= nctive? I would go for the=0A>>> simpler "if the store file name were emb= edded in the source", dropping the 'to be' indirection.=0A>> =0A>> That s= ounds good to me.=0A>> =0A>>> Question: do you know how to decide between= "if X were to be embedded"/"if X were embedded" and "if=0A>>> X was embe= dded"?=0A>> =0A>> 1st case: evokes future anterior; predication is contin= gent & retroactive. Should be used in=0A>> indeterminate circumstances.= =0A>> 2nd case: predication is determined by the present. We can know at = present whether x is currently=0A>> embedded.=0A>> 3rd case: predication = is determined by the past. We can know whether x was *ever* embedded.=0A>= > =0A>> Why?=0A> =0A> I was wondering if the 2nd case is considered corre= ct grammar (even if=0A> maybe not appropriate in this particular case) or= just a personal quirk.=0A> Also, when learning English grammar, it was m= ore based on 'feel' than=0A> explicit rules and consequently it was hard = to decide between (2) and (3).=0A> =0A> I don't know about (1), but (3) i= ndeed doesn't seem appropriate here.=0A> =0A> I'll change it to (2) in th= e next version.=0A> =0A> Greetings,=0A> Maxime.