Definite article in synopsis

Definite article in synopsis

[John Darrington]

[-- Attachment #1: Type: text/plain, Size: 489 bytes --]

I thought we had a policy that the synopsis field must not 
start with an article.  

However running 
	grep 'synopsis  *"The'  *.scm

shows that we have many instances where this policy is
not followed.

Or have I   misunderstood something?

J'

-- 
Avoid eavesdropping.  Send strong encrypted email.
PGP Public key ID: 1024D/2DE827B3 
fingerprint = 8797 A26D 0854 2EAB 0285  A290 8A67 719C 2DE8 27B3
See http://sks-keyservers.net or any PGP keyserver for public key.


[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 181 bytes --]

Re: Definite article in synopsis

[Leo Famulari]

[-- Attachment #1: Type: text/plain, Size: 703 bytes --]

On Wed, Sep 21, 2016 at 12:59:51PM +0200, John Darrington wrote:
> I thought we had a policy that the synopsis field must not 
> start with an article.  
> 
> However running 
> 	grep 'synopsis  *"The'  *.scm
> 
> shows that we have many instances where this policy is
> not followed.
> 
> Or have I   misunderstood something?

It's a minor issue. I think that making many small changes throughout
the master branch will be too disruptive for what is a relatively minor
style issue.

If the change is made, I'd prefer it on core-updates. Merging master
into core-updates and vice versa already requires somebody to resolve a
lot of merge conflicts. I'd rather not add to that burden.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: Definite article in synopsis

[Ben Woodcroft]

On 09/23/2016 10:15 AM, Leo Famulari wrote:
> On Wed, Sep 21, 2016 at 12:59:51PM +0200, John Darrington wrote:
>> I thought we had a policy that the synopsis field must not
>> start with an article.
>>
>> However running
>> 	grep 'synopsis  *"The'  *.scm
>>
>> shows that we have many instances where this policy is
>> not followed.
>>
>> Or have I   misunderstood something?
> It's a minor issue. I think that making many small changes throughout
> the master branch will be too disruptive for what is a relatively minor
> style issue.
This is true even though changing a description doesn't trigger a rebuild?

> If the change is made, I'd prefer it on core-updates. Merging master
> into core-updates and vice versa already requires somebody to resolve a
> lot of merge conflicts. I'd rather not add to that burden.
Do you have any recommendations for changing our practices to ease this 
issue?

ben

Re: Definite article in synopsis

[John Darrington]

[-- Attachment #1: Type: text/plain, Size: 1053 bytes --]

On Thu, Sep 22, 2016 at 08:15:51PM -0400, Leo Famulari wrote:
     On Wed, Sep 21, 2016 at 12:59:51PM +0200, John Darrington wrote:
     > I thought we had a policy that the synopsis field must not 
     > start with an article.  
     > 
     > However running 
     > 	grep 'synopsis  *"The'  *.scm
     > 
     > shows that we have many instances where this policy is
     > not followed.
     > 
     > Or have I   misunderstood something?
     
     If the change is made, I'd prefer it on core-updates. Merging master
     into core-updates and vice versa already requires somebody to resolve a
     lot of merge conflicts. I'd rather not add to that burden.

I don't follow the reasoning.  Makeing such a change on core-updates instead of
master would only make the merge effort worse.

J'



-- 
Avoid eavesdropping.  Send strong encrypted email.
PGP Public key ID: 1024D/2DE827B3 
fingerprint = 8797 A26D 0854 2EAB 0285  A290 8A67 719C 2DE8 27B3
See http://sks-keyservers.net or any PGP keyserver for public key.


[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 181 bytes --]

Re: Definite article in synopsis

[Leo Famulari]

On Fri, Sep 23, 2016 at 10:32:56AM +1000, Ben Woodcroft wrote:
> On 09/23/2016 10:15 AM, Leo Famulari wrote:
> > On Wed, Sep 21, 2016 at 12:59:51PM +0200, John Darrington wrote:
> > > I thought we had a policy that the synopsis field must not
> > > start with an article.
> > > 
> > > However running
> > > 	grep 'synopsis  *"The'  *.scm
> > > 
> > > shows that we have many instances where this policy is
> > > not followed.
> > > 
> > > Or have I   misunderstood something?
> > It's a minor issue. I think that making many small changes throughout
> > the master branch will be too disruptive for what is a relatively minor
> > style issue.
> This is true even though changing a description doesn't trigger a rebuild?

I figured that there were hundreds of instances, but checking for "A"
and "An" (what `guix lint` checks for), it's only 8 packages. So I don't
think this change will be disruptive.

My comment about the change being "disruptive" was not about rebuilding
but rather code "churn". And non-functional code churn does seem worth
the human time required to merge hundreds of conflicts.

Is there a reason to remove "The"? I think it would not always be an
improvement, for example in a case like this:

(synopsis "The Erlang programming language")

> > If the change is made, I'd prefer it on core-updates. Merging master
> > into core-updates and vice versa already requires somebody to resolve a
> > lot of merge conflicts. I'd rather not add to that burden.
> Do you have any recommendations for changing our practices to ease this
> issue?

One idea is to do big widespread non-functional changes between
core-updates branches. That is, immediately after a release is tagged,
before a new core-updates branch is required.

Re: Definite article in synopsis

[Ludovic Courtès]

Hello!

Leo Famulari <leo@famulari.name> skribis:

> On Fri, Sep 23, 2016 at 10:32:56AM +1000, Ben Woodcroft wrote:
>> On 09/23/2016 10:15 AM, Leo Famulari wrote:
>> > On Wed, Sep 21, 2016 at 12:59:51PM +0200, John Darrington wrote:
>> > > I thought we had a policy that the synopsis field must not
>> > > start with an article.
>> > > 
>> > > However running
>> > > 	grep 'synopsis  *"The'  *.scm
>> > > 
>> > > shows that we have many instances where this policy is
>> > > not followed.
>> > > 
>> > > Or have I   misunderstood something?
>> > It's a minor issue. I think that making many small changes throughout
>> > the master branch will be too disruptive for what is a relatively minor
>> > style issue.
>> This is true even though changing a description doesn't trigger a rebuild?
>
> I figured that there were hundreds of instances, but checking for "A"
> and "An" (what `guix lint` checks for), it's only 8 packages. So I don't
> think this change will be disruptive.
>
> My comment about the change being "disruptive" was not about rebuilding
> but rather code "churn". And non-functional code churn does seem worth
> the human time required to merge hundreds of conflicts.

I think it’s OK to have occasional “churn” like this, but I agree that
we must make sure to always make such changes on the same branch to
avoid merge conflicts; ‘master’ is OK, both ‘master’ and ‘core-updates’
is not OK.

> Is there a reason to remove "The"? I think it would not always be an
> improvement, for example in a case like this:
>
> (synopsis "The Erlang programming language")

I think the rationale was that it’s often an indication that the
synopsis starts a sentence, but I agree that in some cases this rule
doesn’t work.

>> > If the change is made, I'd prefer it on core-updates. Merging master
>> > into core-updates and vice versa already requires somebody to resolve a
>> > lot of merge conflicts. I'd rather not add to that burden.
>> Do you have any recommendations for changing our practices to ease this
>> issue?
>
> One idea is to do big widespread non-functional changes between
> core-updates branches. That is, immediately after a release is tagged,
> before a new core-updates branch is required.

I would tend to think of ‘master’ as the branch for non-functional
changes like this.  But the key is to make sure such wide changes are
kept in a single branch to avoid merge issues as you wrote.

WDYT?

Thanks,
Ludo’.

Re: Definite article in synopsis

[Leo Famulari]

On Sat, Sep 24, 2016 at 11:28:14AM +0900, Ludovic Courtès wrote:
> I would tend to think of ‘master’ as the branch for non-functional
> changes like this.  But the key is to make sure such wide changes are
> kept in a single branch to avoid merge issues as you wrote.
> 
> WDYT?

To clarify, for this case I think it's not a problem to make the change.
At most it's only ~40 packages, and that's only ~1% of all our packages
:)