Re: Your commit 7409a79

[Stephen Leake]

Eli Zaretskii <address@hidden> writes:

>> From: Stephen Leake <address@hidden>
>> Date: Sat, 06 Dec 2014 16:33:47 -0600
>> 
>> Eli Zaretskii <address@hidden> writes:
>> 
>> >   commit 7409a79b1b2acf1229dd763f5eb7b96abc17113a
>> >   Author: Stephen Leake <address@hidden>
>> >   Date:   Fri Dec 5 13:13:55 2014 -0600
>> >
>> >       preparing for further changes/cleanup to developers/contributors docs
>> >
>> >       * etc/CONTRIBUTE: renamed to ./CONTRIBUTE,
>> >
>> > Please always start the commit log summary line with a capital letter,
>> > and end the sentence with a period.
>> 
>> Do we really need to be so picky?
>
> It's just a good style.
>
>> Note that the Gnu coding standard does _not_ discuss this level of
>> detail, although all the examples do have capitals and periods
>> (http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs).
>
> Exactly.  Also, all the other entries in Emacs's own logs.

Ok, I'm arguing for changing a long-standing practice; that requires a
good reason.

>> 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.

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

> Writing correct English is a basic requirement,
> it doesn't even have to be in the document.  Like correct spelling,
> for example.

Correct spelling of computer language symbols is required because
compilers/interpreters are very picky.

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).

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

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

Stefan said "we should not worry about this", but I'm not clear how much
lack of proper English punctiation he's agreeing to.


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.

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.

>> > (Actually, in the above
>> > particular case the summary line is redundant and could be omitted --
>> > but this is a stylistic comment, not a requirement.)
>> 
>> I tried that:
>> 
>> * etc/CONTRIBUTE: renamed to ./CONTRIBUTE, preparing for further
>> changes/cleanup to developers/contributors docs
>
> The "preparing for" part doesn't need to be there, it has exactly zero
> importance in the context of a commit log.
>
>> I didn't want to just do:
>> 
>> * 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.

The classic example in this case is two developers that have different
visions about what needs to be done, and keep undoing each other's
changes (in this case, moving CONTRIBUTE back to etc). If there is no
documentation of _why_, there is no way to resolve that cycle.

> You could also point to the list discussion, if you really think
> people will need to know why you moved the file.

That would be better; I'm not used to having a permanent archive around
to reference.

> 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.

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).

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 :).

-- 
-- Stephe