Re: Your commit 7409a79

[Eli Zaretskii]

> From: Stephen Leake <address@hidden>
> Date: Sun, 07 Dec 2014 16:39:13 -0600
> 
> >> I see this pickiness as a mild barrier to contributing
> >
> > I don't think it is.  
> 
> I made a statement of fact about myself. I intended to imply that there
> could easily be others that feel the same.
> 
> Your statement, taken literally, says I am wrong about what I feel;
> absurd, and not helpful.

Your statement didn't imply it was about yourself.  To make that
clear, you should have said something like "it is a mild barrier for
my contributing".  (Which would surprise me coming from someone who
writes English poetry for a hobby, but I guess you learn something new
every day.)

> Instead, I will take it to mean, "I (Eli) don't feel that way". That's
> fine. Still not helpful.

I responded to the implied generalization of your feelings to be true
for others.  You didn't give any reasoning for your assessments, so I
didn't feel obliged to provide mine.  It's just your opinion against
mine at this stage.  Nothing wrong about differences of opinions, is
there?  Cause I feel like after a cold shower, and frankly don't
understand why I deserved one.  If this is going to be a frequent kind
of response to any mentoring attempt around here, I'll probably think
twice before trying that again.

> Correct spelling in general is certainly less annoying to read.
> 
> Incorrect punctuation is much less annoying than incorrect spelling (to
> me, at least. Apparently not to you).

Apart of being less annoying, it also looks better for posterity.  All
those random bits and pieces we write are forever sealed in the
Internet records.  Doing it right will save us from being mildly
ashamed down the road.

Last, but not least: we do want Emacs to be as close to perfect as
possible, don't we?  Why the objection to an attempt to educate
contributors in that direction?  Your commit message is immutable, so
whatever I wrote had an implicit "in the future" prepended to it.  Why
would someone object to make their prose in the future better?  There
was no reprimand in what I wrote, just good will and good advice.

> To go to one extreme; non-English speakers will have a much harder time
> than I of getting all of this right.

Given enough guidance and mentoring, they will learn in time; if we
refrain from guiding them, they are less likely to acquire these
skills.  If nothing else, people with these skills are valued higher
on the market, and are easier to communicate with in this age of
international trade and distributed development.  So it's for their
own good, as well as for ours.

I am a non-native English speaker; I wasn't born with the English
writing skills I possess now.  I learned them by listening to Richard
and others, who patiently explained how the text I wrote could and
should be improved.  I'm just trying to give some of that back.

> In light of the general discussion about the high barriers to becoming
> an Emacs contributor, I'm suggesting we seriously consider lowering this
> one.

I stand by my opinion above.  It could be overridden, of course, but I
wonder how low we will agree to descend in the name of "lowering the
barriers".  Especially since this particular barrier is yet to be
proven to be one.

> Since there is some disagreement about this issue among current
> developers, I will adopt the following interpretation of the rules as
> written:
> 
>     Developers are strongly encouraged to use fully proper English, but
>     not doing so is not a reason to reject commits, nor to be
>     chastised/gently reminded on the emacs-devel mailing list, unless
>     the deviation actually causes misunderstanding.

This text is not useful, IMO, because it'sa kind of oxymoron: it
basically says two contradicting things.  Trying to read this as a
newcomer, I find it hard to understand what is it that is required
from me.

> If you disagree with the above, please edit ./CONTRIBUTE to say what you
> want more clearly. Include a rationale, so we don't cycle on this
> endlessly.

First, I understand you are still working on CONTRIBUTE (and have
unpushed changes), so I don't think it's a good idea for me to start
changing it from under your feet.

More importantly, CONTRIBUTE isn't a good platform for discussions and
arguments, so we should reach some agreement here, and only later
write it down.

> >> * etc/CONTRIBUTE: renamed to ./CONTRIBUTE
> >> 
> >> since that doesn't say anything about _why_.
> >
> > You don't need to say why.  

> Ah. Here we have a fundamental misunderstanding/disagreement of what
> commit logs are for.

No, I don't think we do.  It's not about the need to explain in
general, it is about the need for it in this particular case, because
better alternatives exists.

> > You could push all the changes to the
> > file, including its move, as a single commit, or a merge-commit with a
> > single explanatory line.  In general, keeping related changes together
> > requires less explanations.
> 
> I didn't do that because git does not track renames explicitly; it
> relies on a % changed heuristic. Since I was planning to make extensive
> changes, I decided to make separate commits to help the heuristic.

Note the "merge-commit" alternative above: it would have solved the
renaming issue (if you even perceive it as an issue: many Git users
don't, and evidently neither do Git developers).

> This should go in CONTRIBUTE, now that I think about it (and if it's
> not a problem in practice, that should be stated as well, so others
> don't make my mistake).

I don't know what "it" alludes to here, but if you want to suggest
separating renames from other changes, it would most probably be the
wrong advice, unless you also suggest to make all this on a branch and
then merge onto master in a single merge-commit.  Related changes
should be committed together as a single changeset (something that
suddenly disappeared from our instructions).  In this particular case,
renaming alone makes no sense, at least not on the mainline, and if we
ever wanted to revert it, it will most probably be reverted with all
the other changes.  So it makes very little sense to have a separate
mainline commit for just the renaming.

> Now I realize the commit message should have been:
> 
> http:/<archive reference>; no other changes to help the git rename
> heuristic
> 
> Still longer than 79 chars; I'm going to hit that limit a lot (note that
> I am _not_ begging to change it; one fight at a time :).

There's any number of ways to fix this, while still staying on a
single line.  I suggested some, but there are others.  E.g., if you
still believe this should have been a separate mainline commit, you
could have used this:

 CONTRIBUTE: Moved from etc/CONTRIBUTE.

 This is in preparation for restructuring of developer contribution
 documents; see http:/<archive reference> for the related discussion,
 and see http:/<archive reference> for the decision to move the file.

This has a short summary line which tells enough in "git log" short
formats, and then the details below, including the rationale.

But this all is a creative, stylistic issue, not something to be
codified in mandatory documents.  There is no single solution to this;
as long as people choose a reasonable one, and don't goof with
misspellings or missing punctuation, they should be OK.