Your commit 7409a79

Your commit 7409a79

[Eli Zaretskii]

  commit 7409a79b1b2acf1229dd763f5eb7b96abc17113a
  Author: Stephen Leake <stephen_leake@stephe-leake.org>
  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.  (Actually, in the above
particular case the summary line is redundant and could be omitted --
but this is a stylistic comment, not a requirement.)

Also, renaming a file needs an entry in the target's ChangeLog, like
this:

  * CONTRIBUTE: Renamed from etc/CONTRIBUTE.

and it also should end with a period, not a comma.

Thanks.

Re: Your commit 7409a79

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

> Please always start the commit log summary line with a capital letter,
> and end the sentence with a period.

The summary line should not end with a period, like the title of a
document.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Your commit 7409a79

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Cc: Stephen Leake <stephen_leake@stephe-leake.org>,  emacs-devel@gnu.org
> Date: Sat, 06 Dec 2014 11:22:34 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Please always start the commit log summary line with a capital letter,
> > and end the sentence with a period.
> 
> The summary line should not end with a period, like the title of a
> document.

Okay, but then (a) we should codify that, and (b) the summary line
should certainly not end with a comma.

Re: Your commit 7409a79

[Paul Eggert]

Andreas Schwab wrote:
> The summary line should not end with a period

Both styles are OK, if you ask me.  My mild suggestion would be: if the summary 
line is a sentence, end it with a period; if not, not.  Often, summary lines are 
simple imperative sentences like "Improve CONTRIBUTE and related files." and 
that should be fine.  If the summary is "New macro `define-inline'" it might be 
better to omit the trailing period.  Either way, it's not a big deal.

Re: Your commit 7409a79

[Yuri Khan]

On Sat, Dec 6, 2014 at 4:22 PM, Andreas Schwab <schwab@linux-m68k.org> wrote:
> Eli Zaretskii <eliz@gnu.org> writes:
>
>> Please always start the commit log summary line with a capital letter,
>> and end the sentence with a period.
>
> The summary line should not end with a period, like the title of a
> document.

Technically, the summary line of the commit being discussed is:

preparing for further changes/cleanup to developers/contributors docs


Many projects using Git have a convention that the commit summary is
an imperative phrase:

Prepare for further changes/cleanup to developers/contributors docs

This way, commit summaries are useful as a rebase TODO list and they
work well with the default merge commit message.


Also, the subject line of this discussion should have been:

Re: preparing for further changes/cleanup to developers/contributors docs

as if the commit were an email sent to a patches list.

Re: Your commit 7409a79

[Stefan Monnier]

> The summary line should not end with a period, like the title of a
> document.

I think we should not care about this.


        Stefan

Re: Your commit 7409a79

[Tom]

Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> Please always start the commit log summary line with a capital letter,
> and end the sentence with a period.  (Actually, in the above
> particular case the summary line is redundant and could be omitted --
> but this is a stylistic comment, not a requirement.)
> 
> Also, renaming a file needs an entry in the target's ChangeLog, like
> this:
> 
>   * CONTRIBUTE: Renamed from etc/CONTRIBUTE.
> 
> and it also should end with a period, not a comma.
> 

These are exactly the situations where a server side commit hook
is really useful for the following reasons:

1. It prevent commits with incorrectly formatted commit messages.

2. It prints an error message describing the problem, thereby
teaching the committer how to make a properly formatted commit.

So there is no need for manually replying to incorrect commits
on the list, because the script checks every commit and even 
tells the user the problem.

So it would be a good idea to add such a precommit script to the
server.

Re: Your commit 7409a79

[Eli Zaretskii]

> From: Tom <adatgyujto@gmail.com>
> Date: Sat, 6 Dec 2014 16:14:42 +0000 (UTC)
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> > 
> > Please always start the commit log summary line with a capital letter,
> > and end the sentence with a period.  (Actually, in the above
> > particular case the summary line is redundant and could be omitted --
> > but this is a stylistic comment, not a requirement.)
> > 
> > Also, renaming a file needs an entry in the target's ChangeLog, like
> > this:
> > 
> >   * CONTRIBUTE: Renamed from etc/CONTRIBUTE.
> > 
> > and it also should end with a period, not a comma.
> > 
> 
> These are exactly the situations where a server side commit hook
> is really useful for the following reasons:

The intent of my message was to explain how to prepare good log
messages that will not trigger any hook which will reject the commit.
Apart of having more people follow the standards to begin with,
avoiding such rejection is a Good Thing because while one fixed a
rejected push, someone else could push and force you to pull/rebase.

IOW, don't overestimate automated hooks and don't underestimate the
value of education.

Re: Your commit 7409a79

[Stephen Leake]

Tom <adatgyujto@gmail.com> writes:

> Eli Zaretskii <eliz <at> gnu.org> writes:
>> 
>> Please always start the commit log summary line with a capital letter,
>> and end the sentence with a period.  (Actually, in the above
>> particular case the summary line is redundant and could be omitted --
>> but this is a stylistic comment, not a requirement.)
>> 
>> Also, renaming a file needs an entry in the target's ChangeLog, like
>> this:
>> 
>>   * CONTRIBUTE: Renamed from etc/CONTRIBUTE.
>> 
>> and it also should end with a period, not a comma.
>> 
>
> These are exactly the situations where a server side commit hook
> is really useful for the following reasons:
>
> 1. It prevent commits with incorrectly formatted commit messages.

To be precise, if it's only running on the server (Savannah), it does
not prevent the _commit_, it prevents the _push_.

There are a couple commit hooks in emacs/.git/hooks set by autogen.sh
(amazing what you learn reading commit logs :); we could add a hook
there to do this check.

vc could check for proper formatting before doing the commit. Catching
errors as early as possible is always better.

Of course, it would be even better if vc would silently fix the
formatting.

> 2. It prints an error message describing the problem, thereby
> teaching the committer how to make a properly formatted commit.
>
> So there is no need for manually replying to incorrect commits
> on the list, because the script checks every commit and even 
> tells the user the problem.
>
> So it would be a good idea to add such a precommit script to the
> server.

If we go this route, let's also add some vc functionality that checks
and/or does the formatting, and make sure the commit error message
mentions both CONTRIBUTE and the vc function.

-- 
-- Stephe

Re: Your commit 7409a79

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

>   commit 7409a79b1b2acf1229dd763f5eb7b96abc17113a
>   Author: Stephen Leake <stephen_leake@stephe-leake.org>
>   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?

I agree there should be no comma here; that makes it an
incomplete statement.

But I don't think capitals and periods actually improve readability in
this context; it's _not_ a manual, nor a code comment.

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

I see this pickiness as a mild barrier to contributing, so I'd like to
get some more rationale before I add this to CONTRIBUTE.

And then I'll have to write some elisp to do that level of formatting
(if someone hasn't already).

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

But that was rejected by the commit filter as being longer than 79
chars.

I didn't want to just do:

* etc/CONTRIBUTE: renamed to ./CONTRIBUTE

since that doesn't say anything about _why_.

> Also, renaming a file needs an entry in the target's ChangeLog,

Yes, I messed up the commit process. I did edit ChangeLog, but then
forgot to stage it (and no, I'm not using 'git commit -a'). It's in the
next commit. I'll get there.

> like this:
>
>   * CONTRIBUTE: Renamed from etc/CONTRIBUTE.
>
> and it also should end with a period, not a comma.

Yes, the comma was a cut-and-paste error from the first attempt.

--
-- Stephe

Re: Your commit 7409a79

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Sat, 06 Dec 2014 16:33:47 -0600
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >   commit 7409a79b1b2acf1229dd763f5eb7b96abc17113a
> >   Author: Stephen Leake <stephen_leake@stephe-leake.org>
> >   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.

> I see this pickiness as a mild barrier to contributing

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

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

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

Also, saying it's "in preparation" of something doesn't really explain
why, since a file can be changed without moving it.

Re: Your commit 7409a79

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stephen Leake <stephen_leake@stephe-leake.org>
>> Date: Sat, 06 Dec 2014 16:33:47 -0600
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >   commit 7409a79b1b2acf1229dd763f5eb7b96abc17113a
>> >   Author: Stephen Leake <stephen_leake@stephe-leake.org>
>> >   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

Re: Your commit 7409a79

[Paul Eggert]

Stephen Leake wrote:
> Now I realize the commit message should have been:
>
> http:/<archive reference>; no other changes to help the git rename
> heuristic

When a commit merely renames files, wouldn't it be better for the subject line 
to explain the underlying reason for the change?  Something like this, perhaps: 
"Rename old ChangeLog files to prepare for gitlog-to-changelog."  That would be 
easier to follow than some URL.  Any URL could be placed in later lines in the 
commit message.

> Still longer than 79 chars; I'm going to hit that limit a lot

The limit is currently 72 characters (unless the line has just one word).

Some projects also have a separate limit of 50 characters for subject lines; for 
example, please see 
<http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>.  But 
this might be a bit too short for Emacs.

Re: Your commit 7409a79

[Stephen J. Turnbull]

Paul Eggert writes:

 > When a commit merely renames files, wouldn't it be better for the
 > subject line to explain the underlying reason for the change?

If the rename is out of the blue, yes.  But when does that happen?
Almost always renames happen in the context of other work and multiple
commits (some "pure renames" and some content changes) makes sense.

I would do the other work that the rename is intended to support on a
branch, do the rename, and then a merge commit with a commit message
like

    Clarify CONTRIBUTE and make it prominently visible.

    Step one in a revolutionary program to attract more contributors
    to Emacs.

    - Move from etc/ to top level for visibility in ls and git-browser.
    - Specify format of commit log summaries.
    - etc, etc

Then the rename commit can be trivial with a simple statement of fact:

    Rename etc/CONTRIBUTE to ./CONTRIBUTE.

Of course this style of committing and logs would be an insuperable
barrier to contribution if it were made policy. ;-)

Regards,

Re: Your commit 7409a79

[Eli Zaretskii]

> From: "Stephen J. Turnbull" <stephen@xemacs.org>
> Date: Mon, 08 Dec 2014 11:28:48 +0900
> Cc: Stephen Leake <stephen_leake@stephe-leake.org>, emacs-devel@gnu.org
> 
> I would do the other work that the rename is intended to support on a
> branch, do the rename, and then a merge commit with a commit message
> like
> 
>     Clarify CONTRIBUTE and make it prominently visible.
> 
>     Step one in a revolutionary program to attract more contributors
>     to Emacs.
> 
>     - Move from etc/ to top level for visibility in ls and git-browser.
>     - Specify format of commit log summaries.
>     - etc, etc
> 
> Then the rename commit can be trivial with a simple statement of fact:

Exactly my thoughts.

>     Rename etc/CONTRIBUTE to ./CONTRIBUTE.
> 
> Of course this style of committing and logs would be an insuperable
> barrier to contribution if it were made policy. ;-)

If people object to having instructions in CONTRIBUTE that might be
not 100% necessary, I wonder if we can put recommendations in
CONTRIBUTE without making it a policy that is enforced.  Something
like "we recommend ...".

Re: Your commit 7409a79

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: "Stephen J. Turnbull" <stephen@xemacs.org>
>> Date: Mon, 08 Dec 2014 11:28:48 +0900
>> Cc: Stephen Leake <stephen_leake@stephe-leake.org>, emacs-devel@gnu.org
>> 
>> I would do the other work that the rename is intended to support on a
>> branch, do the rename, and then a merge commit with a commit message
>> like
>> 
>>     Clarify CONTRIBUTE and make it prominently visible.
>> 
>>     Step one in a revolutionary program to attract more contributors
>>     to Emacs.
>> 
>>     - Move from etc/ to top level for visibility in ls and git-browser.
>>     - Specify format of commit log summaries.
>>     - etc, etc
>> 
>> Then the rename commit can be trivial with a simple statement of fact:
>
> Exactly my thoughts.
>
>>     Rename etc/CONTRIBUTE to ./CONTRIBUTE.
>> 
>> Of course this style of committing and logs would be an insuperable
>> barrier to contribution if it were made policy. ;-)
>
> If people object to having instructions in CONTRIBUTE that might be
> not 100% necessary, I wonder if we can put recommendations in
> CONTRIBUTE without making it a policy that is enforced.  Something
> like "we recommend ...".

We can use "shall" or "must" for requirements, "should" for
recommendations. That's standard NASA practice.

That is _not_ the language used in the Gnu coding standards; that uses
"should" and "please" and other random words. It's not at all clear how
that relates to required/recommended.

-- 
-- Stephe

Re: Your commit 7409a79

[Eli Zaretskii]

> Date: Sun, 07 Dec 2014 17:57:27 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> 
> Stephen Leake wrote:
> 
>     Now I realize the commit message should have been:
> 
>     http:/<archive reference>; no other changes to help the git rename
>     heuristic
> 

> When a commit merely renames files, wouldn't it be better for the subject line to explain the underlying reason for the change? Something like this, perhaps: "Rename old ChangeLog files to prepare for gitlog-to-changelog." That would be easier to follow than some URL. Any URL could be placed in later lines in the commit message.

I see no reason for the explanation to be in the summary.  If you look
at the existing summary lines, you will see that they always say what
was done, but not why.  At least one reason for that is that including
the explanation will most likely violate the "one line of less than 80
characters" rule.

Re: Your commit 7409a79

[Paul Eggert]

On 12/08/2014 07:58 AM, Eli Zaretskii wrote:
>> From: Paul Eggert<eggert@cs.ucla.edu>
>> >
>> >Stephen Leake wrote:
>> >
>> >     Now I realize the commit message should have been:
>> >
>> >     http:/<archive reference>; no other changes to help the git rename
>> >     heuristic
>> >
>> >When a commit merely renames files, wouldn't it be better for the subject line to explain the underlying reason for the change? Something like this, perhaps: "Rename old ChangeLog files to prepare for gitlog-to-changelog." That would be easier to follow than some URL. Any URL could be placed in later lines in the commit message.
> I see no reason for the explanation to be in the summary.

Although explanations don't always need to be in the summary, for 
something this small (where the entire commit message can fit into one 
line) it's better to do it that way.

The summary in Stephen Leake's draft commit message was 
"http://something-or-another; no other changes to help the git rename". 
That is less helpful than "Rename ChangeLogs to prep for 
gitlog-to-changelog" (see, it fits 50 characters!).

Re: Your commit 7409a79

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> 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.

Re: Your commit 7409a79

[John Yates]

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

On Mon, Dec 8, 2014 at 10:51 AM, Eli Zaretskii <eliz@gnu.org> wrote:

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

While GNU ChangeLog conventions may be off-putting to those we
hope to recruit git subject line hygiene is widely discussed, documented
and viewed as a "best practice".  Failure to practice it ourselves is more
likely to be viewed as one more instance of our being out of touch with
the better elements of emerging practice than as a boon to new recruits.

/john

[-- Attachment #2: Type: text/html, Size: 992 bytes --]

Re: Your commit 7409a79

[Eli Zaretskii]

> Date: Mon, 8 Dec 2014 12:32:36 -0500
> From: John Yates <john@yates-sheets.org>
> Cc: Stephen Leake <stephen_leake@stephe-leake.org>, Emacs developers <emacs-devel@gnu.org>
> 
>     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.
>     
> 
> While GNU ChangeLog conventions may be off-putting to those we
> hope to recruit git subject line hygiene is widely discussed, documented
> and viewed as a "best practice". Failure to practice it ourselves is more
> likely to be viewed as one more instance of our being out of touch with
> the better elements of emerging practice than as a boon to new recruits.

Not sure what your point is here.  My comment above was in teh context
of a request to use full sentences as summary lines.  Is that a
"failure to practice git subject line hygiene"?  If so, in what ways?

Re: Your commit 7409a79

[Paul Eggert]

On 12/08/2014 09:57 AM, Eli Zaretskii wrote:
> My comment above was in the context
> of a request to use full sentences as summary lines.  Is that a
> "failure to practice git subject line hygiene"?
Yes, absolutely.  The typical Git style has no period at the end. See, 
for example, "The seven rules of a great git commit message" 
<http://chris.beams.io/posts/git-commit/>, one of which is "Do not end 
the subject line with a period". This is a slight change from the style 
we've mostly been using, which has a period.

Perhaps we should change to the typical Git style.  We might also prefer 
to shorten the summary lines to 50 characters, as that is is also part 
of the usual Git style.

Re: Your commit 7409a79

[Eli Zaretskii]

> Date: Mon, 08 Dec 2014 10:14:18 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> CC: emacs-devel@gnu.org
> 
> On 12/08/2014 09:57 AM, Eli Zaretskii wrote:
> > My comment above was in the context
> > of a request to use full sentences as summary lines.  Is that a
> > "failure to practice git subject line hygiene"?
> Yes, absolutely.  The typical Git style has no period at the end.

I already agreed to no-period format.  It can still be a full
sentence.

> We might also prefer to shorten the summary lines to 50 characters,
> as that is is also part of the usual Git style.

If someone can write a meaningful summary in 50 characters every time,
chapeau.  IMO, it is more important for the summary to be informative
than it is to be short.

Re: Your commit 7409a79

[Eli Zaretskii]

> Date: Mon, 08 Dec 2014 10:14:18 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> Cc: emacs-devel@gnu.org
> 
> We might also prefer to shorten the summary lines to 50 characters,
> as that is is also part of the usual Git style.

I don't see this being adhered to seriously.  E.g.:

  commit 08a713e078f03e7a870b0111960c6f4c54357152
  Author: Paul Eggert <eggert@cs.ucla.edu>
  Date:   Sun Nov 2 22:24:09 2014 -0800

      open, openat: document nonstandard FreeBSD, NetBSD O_NOFOLLOW errno

      * doc/posix-functions/open.texi (open):
      * doc/posix-functions/openat.texi (openat):
      Document that these functions do not set errno to ELOOP when
      a symlink is opened with O_NOFOLLOW.

and similarly in Git's Git repo.

(Btw, I think the above is a pretty good summary line.)

Re: Your commit 7409a79

[Paul Eggert]

On 12/08/2014 10:37 AM, Eli Zaretskii wrote:
> I don't see this being adhered to seriously.

Although Gnulib established its own style for git commit messages, the 
usual Git style is reasonable, it's not that hard to use, and it is a 
bit nicer when reviewing large quantities of commits.  The sample you 
just gave could have been summarized "openat etc.: document oddball BSD 
O_NOFOLLOW errno", for example, and that fits in 50.

Re: Your commit 7409a79

[Stefan Monnier]

> Perhaps we should change to the typical Git style.

As far as I know, we've indeed asked for punctuation in the ChangeLog
(and I've added my share of such missing "."), but for the Summary line
we don't really have a convention in place and I suggest we don't bother
with one.  I do like those summaries to be properly capitalized, tho.


        Stefan

Re: Your commit 7409a79

[John Yates]

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

On Mon, Dec 8, 2014 at 12:57 PM, Eli Zaretskii <eliz@gnu.org> wrote:

> Not sure what your point is here.  My comment above was in teh context
> of a request to use full sentences as summary lines.  Is that a
> "failure to practice git subject line hygiene"?  If so, in what ways?
>

My apologies for being obtuse.  Perhaps as a git user for some while
I assumed more familiarity with git culture than exists in this thread.

I was merely pointing out that across many important projects there
are rather stringent standards for the subject line of a git commit.
These cover line length, no trailing period, imperative mood, etc.

So actually Eli I was supporting your stance of resisting "lowering
the barriers".

/john

[-- Attachment #2: Type: text/html, Size: 1171 bytes --]

Re: Your commit 7409a79

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stephen Leake <stephen_leake@stephe-leake.org>
>> 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".

Fair enough; I'll try to be clearer in the future. I should have said:

    For me, this pickiness is a mild barrier to contributing. I suspect
    the same is true for others.

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

Ok.

> It's just your opinion against
> mine at this stage.  Nothing wrong about differences of opinions, is
> there?

Right.

> Cause I feel like after a cold shower, and frankly don't
> understand why I deserved one.

That's how I felt reading your response. Sigh; email is not the best
communications mechanism.

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

Ok, that makes sense. This is going in the ChangeLog, as well as just
the commit message; that is more of a document than a transient thing.
And the commit messages are preseved indefinitely in the git repository,
so there's a good chance they will be read in the future.

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

Because I have been trying for 30 years to make myself write caps and
periods in commit messages, and it just doesn't work for me (mostly
because I just don't see it as important). Hence the barrier to
contributing.

> There was no reprimand in what I wrote, just good will and good
> advice.

I got the impression of "if you don't follow this advice, your commits
will be rejected/not taken seriously". That's _not_ from your text, just
from your position of core developer, and mine as Emacs newbie. And
because there is no clear documentation of what the standards are.

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

That's what ediff/merge is for.

But I gather there is an aversion to lots of small commits; that's not
the style I used with my NASA team. But that was a much smaller team, so
I'll have to get used to this.

Anyway, I've added:

- Some of the rules in the GNU coding standards section 5.2 Commenting
  Your Work also apply to Changelog entries: they must be in English,
  and be complete sentences starting with a capital and ending with a
  period. It is tempting to relax this rule for commit messages, since
  they are somewhat transient. However, they are preserved indefinitely,
  and have a reasonable chance of being read in the future, so it's
  better that they have good presentation.

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

I was attempting to pass the buck. But I'll accept your rationale.

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

As I understand it, by "merge-commit", you mean :

- create a feature branch

- On the feature branch, commit the rename without any changes

- make other changes on the feature branch

- merge the feature branch to trunk, squashing the commits into one.

But "squash all the commits into one" means the Git rename hueristic has
to cope with the changes, which is what I was trying to avoid.

(see; inconsistent caps, periods in the above bullet list; they just
slow me down :)

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

It's a big stretch to go from the examples in the Gnu coding standards
to this example. There are some like this in ./Changelog; first one
2014-11-11 Eric S. Raymond <esr@thyrsus.com>, and that has a leading
asterisk on the first line.

It's my impression that it is exactly this kind of style issue that
started this whole thread, so I'd like to have at least a statement of
what will be accepted in CONTRIBUTE. As you said about my paragraph
above, it's not easy to say "some deviations accepted" and still be
clear.

How about:

- The summary line is limited to 72 characters (enforced by a commit
  hook). If you have trouble making that a good summary, add a
  paragraph below it, before the individual file descriptions.

- If only a single file is changed, the summary line be the normal file
  first line (starting with the asterisk). Then there is no individual
  files section.


Diff from the current trunk below.

--
-- Stephe

index dc6fd71..0ceb4af 100644
--- a/CONTRIBUTE
+++ b/CONTRIBUTE
@@ -154,8 +154,9 @@ single short line explaining the change, then an empty line, then
 unindented ChangeLog entries.  (Essentially, a commit message should
 be a duplicate of what the patch adds to the ChangeLog files.  We are
 planning to automate this better, to avoid the duplication.) You can
-use the Emacs functions log-edit-add-to-changelog or
-log-edit-insert-changelog to ease this process.
+use various Emacs functions to ease this process; see
+http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html
+(info "(emacs)Change Log Commands").

 ** The patch itself.

@@ -235,6 +236,14 @@ specify the actual author; the committer defaults to you.

   (Rather than anything involving "ditto" and suchlike.)

+- The summary line is limited to 72 characters (enforced by a commit
+  hook). If you have trouble making that a good summary, add a
+  paragraph below it, before the individual file descriptions.
+
+- If only a single file is changed, the summary line can be the normal
+  file first line (starting with the asterisk).  Then there is no
+  individual files section.
+
 - In ChangeLog files, there is no standard or recommended way to
   identify revisions.

@@ -249,6 +258,17 @@ specify the actual author; the committer defaults to you.
   of files such as 'configure'.  "There is no need" means you don't
   have to, but you can if you want to.

+- Use the present tense; describe "what the change does", not "what
+  the change did".
+
+- Some of the rules in the GNU coding standards section 5.2
+  "Commenting Your Work" also apply to Changelog entries: they must be
+  in English, and be complete sentences starting with a capital and
+  ending with a period.  It is tempting to relax this rule for commit
+  messages, since they are somewhat transient.  However, they are
+  preserved indefinitely, and have a reasonable chance of being read
+  in the future, so it's better that they have good presentation.
+
 ** branches

 Development normally takes places on the trunk.
@@ -287,6 +307,21 @@ then exclude that commit from the merge to trunk.
 See all the files in admin/notes/* . In particular, see
 admin/notes/newfile, see admin/notes/repo.

+*** git vs rename
+
+git does not explicitly represent a file renaming; it uses a percent
+changed heuristic to deduce that a file was renamed. So if you are
+planning to make extensive changes to a file after renaming it (or
+moving it to another directory), you should:
+
+- create a feature branch
+
+- commit the rename without any changes
+
+- make other changes
+
+- merge the feature branch to trunk, squashing the commits into one.
+
 ** Emacs Mailing lists.

 Discussion about Emacs development takes place on emacs-devel@gnu.org.

Re: Your commit 7409a79

[Thien-Thi Nguyen]

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

() Stephen Leake <stephen_leake@stephe-leake.org>
() Mon, 08 Dec 2014 17:27:13 -0600

   Because I have been trying for 30 years to make myself write
   caps and periods in commit messages, and it just doesn't work
   for me (mostly because I just don't see it as important).
   Hence the barrier to contributing.

Maybe if you take a step sideways and consider the role of the
initial caps and period, it will make things easier to not only
accept, but formulate exceptions.  This is my roundabout way of
pushing my own personal axioms re TITLE:

- A sentence begins w/ a capitalized word and ends with period.
- Phrases that are not sentences do not merit this.
- A change can be described by a sentence or a phrase.

The last axiom is the escape hatch that allows TITLEs such as:

 - New module: (foo bar baz)
 - Add abstractions: make-coffee, stumble-about

in place of the excruciatingly "correct":

 - Add module ‘(foo bar baz)’.
 - Add abstractions ‘make-coffee’, ‘stumble-about’.

that the first two axioms alone would require.  (I always
capitalize TITLE, for personal aesthetics -- the salient
difference is lack of trailing dot and lack of quotes.)

In sum, the trick is not to force yourself into a static mold,
but to instead train yourself into the molding mindset, then
apply yourself freely and w/ deliberation, dynamically.

It is, essentially, another form of late binding (insert rainbows
and unicorns, here :-D).

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

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

Re: Your commit 7409a79

[Stephen Leake]

Thien-Thi Nguyen <ttn@gnu.org> writes:

> () Stephen Leake <stephen_leake@stephe-leake.org>
> () Mon, 08 Dec 2014 17:27:13 -0600
>
>    Because I have been trying for 30 years to make myself write
>    caps and periods in commit messages, and it just doesn't work
>    for me (mostly because I just don't see it as important).
>    Hence the barrier to contributing.
>
> Maybe if you take a step sideways and consider the role of the
> initial caps and period, it will make things easier to not only
> accept, but formulate exceptions.  This is my roundabout way of
> pushing my own personal axioms re TITLE:
>
> - A sentence begins w/ a capitalized word and ends with period.
> - Phrases that are not sentences do not merit this.
> - A change can be described by a sentence or a phrase.

Yes.

> The last axiom is the escape hatch that allows TITLEs such as:

Ah, but why limit the exception to the TITLE? The rest of the commit
entry is also describing changes. That's my problem :).

"this will be here for posterity" was _not_ true for the NASA projects I
worked on; it is true for Emacs. I think that will be sufficient
motivation for me.

-- 
-- Stephe

Re: Your commit 7409a79

[Thien-Thi Nguyen]

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

() Stephen Leake <stephen_leake@stephe-leake.org>
() Tue, 09 Dec 2014 02:08:45 -0600

   Ah, but why limit the exception to the TITLE? The rest of the
   commit entry is also describing changes. That's my problem :).

That escape hatch is TITLE-only to conserve space, i suppose.
In the entry BODY, an extra dot at the end (and quoting, YMMV)
is no big deal.  E.g.:

 Add abstraction: mumble
 
 * foo.el (mumble): New func.
 (explain, extemporize, spew): Use it.

Under pervasive axiom 3, this could have been written:

 Add abstraction: mumble
 
 * foo.el (mumble): new func
 (explain, extemporize, spew): Use it.

but that naked "new func" is jarring (i use lowercase "n" for
emphasis) w/in the BODY context.  All IMHO, of course.  Actually,
for this case, to reduce redundancy, i might instead settle on:

 Add abstraction: mumble
 
 * foo.el (mumble): ...here.
 (explain, extemporize, spew): Use it.

as long as i'm comfortable equating "abstraction" w/ "func".
Anyway, writing a style guide is tough work, so kudos to those who
Do It.  I like style guides that include rationale, personally.

   "this will be here for posterity" was _not_ true for the NASA
   projects I worked on; it is true for Emacs.  I think that will
   be sufficient motivation for me.

It's very possible that Emacs will outlast NASA.  I don't think
i'll be around to find out, though...  :-D

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

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

Re: Your commit 7409a79

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Mon, 08 Dec 2014 17:27:13 -0600
> 
> I have been trying for 30 years to make myself write caps and
> periods in commit messages, and it just doesn't work for me (mostly
> because I just don't see it as important). Hence the barrier to
> contributing.

Nothing a simple Lisp function couldn't handle, if installed as a hook
in a proper place, right?

And the period is no longer an issue, so you are down to caps.

> > There was no reprimand in what I wrote, just good will and good
> > advice.

> I got the impression of "if you don't follow this advice, your commits
> will be rejected/not taken seriously". That's _not_ from your text, just
> from your position of core developer, and mine as Emacs newbie. And
> because there is no clear documentation of what the standards are.

Relax, this ain't NASA, and I'm not your boss ;-)  I do expect my
advice to carry some weight, but not enough to prevent you from
arguing if you feel strong about not using caps (or whatever is the
issue at hand).

> > 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).
> 
> As I understand it, by "merge-commit", you mean :
> 
> - create a feature branch
> 
> - On the feature branch, commit the rename without any changes
> 
> - make other changes on the feature branch
> 
> - merge the feature branch to trunk, squashing the commits into one.

The "squashing" part is optional.  Personally, I prefer not to (if
nothing else, it makes bisecting more accurate, and also lets me
recall what I've done and why more easily), although the benefits are
minor, and some people do prefer squashing.

> But "squash all the commits into one" means the Git rename hueristic has
> to cope with the changes, which is what I was trying to avoid.

Then don't squash.  It's not required.  The single merge-commit is
good enough to make this a single changeset, from the mainline POV.

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

> It's a big stretch to go from the examples in the Gnu coding standards
> to this example. There are some like this in ./Changelog; first one
> 2014-11-11 Eric S. Raymond <address@hidden>, and that has a leading
> asterisk on the first line.

Asterisks come from add-change-log-entry and friends, so it will not
be there if you just write free text, like I did above.

In any case, the asterisks are optional, IMO.  They don't carry any
information with them.  I've been deleting them until now, but I hear
some people want to keep them.  Other projects are inconsistent wrt
this, although most of those I looked at do leave the asterisks alone,
probably because it's easier.

> It's my impression that it is exactly this kind of style issue that
> started this whole thread, so I'd like to have at least a statement of
> what will be accepted in CONTRIBUTE.

From experience, the rules are not rigid.  You need to put the right
information there, and make it in correct English, and that's about
all that's really required.  Beyond that, it's all about your
perfectionism.

> How about:
> 
> - The summary line is limited to 72 characters (enforced by a commit
>   hook). If you have trouble making that a good summary, add a
>   paragraph below it, before the individual file descriptions.
> 
> - If only a single file is changed, the summary line be the normal file
>   first line (starting with the asterisk). Then there is no individual
>   files section.

Should be fine.

> +- merge the feature branch to trunk, squashing the commits into one.

I'd suggest "optionally squashing the commits".

Thanks.

Re: Your commit 7409a79

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

>> >  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.
>
>> It's a big stretch to go from the examples in the Gnu coding standards
>> to this example. There are some like this in ./Changelog; first one
>> 2014-11-11 Eric S. Raymond <address@hidden>, and that has a leading
>> asterisk on the first line.
>
> Asterisks come from add-change-log-entry and friends, so it will not
> be there if you just write free text, like I did above.

> In any case, the asterisks are optional, IMO.

http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html
last paragraph says asterisks are part of the required Changelog style.

> From experience, the rules are not rigid.  

True, they are not consistently enforced.

But a new developer needs a clear set of rules, so they know what they
need to change in their habits from other projects.

> You need to put the right information there, and make it in correct
> English, and that's about all that's really required. Beyond that,
> it's all about your perfectionism.

That is not the impression I get from the mentoring comments on this
list, and it is not what it says in CONTRIBUTE.

-- 
-- Stephe

Re: Your commit 7409a79

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Wed, 10 Dec 2014 03:26:39 -0600
> 
> > Asterisks come from add-change-log-entry and friends, so it will not
> > be there if you just write free text, like I did above.
> 
> > In any case, the asterisks are optional, IMO.
> 
> http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html
> last paragraph says asterisks are part of the required Changelog style.

I wasn't talking about Changelog's, I was talking about commit log
messages.

> > You need to put the right information there, and make it in correct
> > English, and that's about all that's really required. Beyond that,
> > it's all about your perfectionism.
> 
> That is not the impression I get from the mentoring comments on this
> list, and it is not what it says in CONTRIBUTE.

You need to read just what the text says, as you yourself admitted.

Re: Your commit 7409a79

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stephen Leake <stephen_leake@stephe-leake.org>
>> Date: Wed, 10 Dec 2014 03:26:39 -0600
>> 
>> > Asterisks come from add-change-log-entry and friends, so it will not
>> > be there if you just write free text, like I did above.
>> 
>> > In any case, the asterisks are optional, IMO.
>> 
>> http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html
>> last paragraph says asterisks are part of the required Changelog style.
>
> I wasn't talking about Changelog's, I was talking about commit log
> messages.

CONTRIBUTE says:

    When using git, commit messages should use ChangeLog format, with a
    ...

>> > You need to put the right information there, and make it in correct
>> > English, and that's about all that's really required. Beyond that,
>> > it's all about your perfectionism.
>> 
>> That is not the impression I get from the mentoring comments on this
>> list, and it is not what it says in CONTRIBUTE.
>
> You need to read just what the text says, as you yourself admitted.

I don't follow; what is your point?

-- 
-- Stephe

Re: Your commit 7409a79

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Wed, 10 Dec 2014 11:04:03 -0600
> 
> >> > In any case, the asterisks are optional, IMO.
> >> 
> >> http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html
> >> last paragraph says asterisks are part of the required Changelog style.
> >
> > I wasn't talking about Changelog's, I was talking about commit log
> > messages.
> 
> CONTRIBUTE says:
> 
>     When using git, commit messages should use ChangeLog format, with a

That's obviously inaccurate.

> >> > You need to put the right information there, and make it in correct
> >> > English, and that's about all that's really required. Beyond that,
> >> > it's all about your perfectionism.
> >> 
> >> That is not the impression I get from the mentoring comments on this
> >> list, and it is not what it says in CONTRIBUTE.
> >
> > You need to read just what the text says, as you yourself admitted.
> 
> I don't follow; what is your point?

That your impression doesn't have any basis, the text of mentoring
comments as written and posted does not imply anything to that effect.

Re: Your commit 7409a79

[Paul Eggert]

On 12/10/2014 10:02 AM, Eli Zaretskii wrote:
>> CONTRIBUTE says:
>> >
>> >     When using git, commit messages should use ChangeLog format, with a
> That's obviously inaccurate.
>

No, it's pretty much correct.  Once we start generating ChangeLogs 
automatically from commit messages, we'll need to use the same 
guidelines for both.  In the meantime we might as well use the same 
guidelines for both.

Re: Your commit 7409a79

[Stephen J. Turnbull]

Stephen Leake writes:
 > Eli Zaretskii <eliz@gnu.org> writes:

 > > Please always start the commit log summary line with a capital letter,
 > > and end the sentence with a period.

 > But I don't think capitals and periods actually improve readability in
 > this context; it's _not_ a manual, nor a code comment.

Just as a point of information (I claim no UX authority), I do find
summaries that are complete sentences more readable.  That may be
because the capital-and-period discipline encourages many writers to
write complete thoughts (vs complete sentences).  Or it may be that
better writers are more likely to write in complete sentences unless
told not to.

Re: Your commit 7409a79

[Stefan Monnier]

>   * CONTRIBUTE: Renamed from etc/CONTRIBUTE.
                  ^^^^^^^
                  Rename

Of course, we also prefer the present tense because the text should
describe "what the patch does" rather than "what the patch did".


        Stefan

Re: Your commit 7409a79

[Stephen Leake]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>   * CONTRIBUTE: Renamed from etc/CONTRIBUTE.
>                   ^^^^^^^
>                   Rename
>
> Of course, we also prefer the present tense because the text should
> describe "what the patch does" rather than "what the patch did".

Ok. I often switch tenses halfway thru, and then get annoyed when I
realize that. Having a standard will help.

Added to CONTRIBUTE (not pushed yet).


Gentle reminder; when making comments about commit log style, please
reference CONTRIBUTE. And if what you are saying is _not_ currently in
CONTRIBUTE, please fix it (or don't say it :).


-- 
-- Stephe

Re: Your commit 7409a79

[Stefan Monnier]

> Ok. I often switch tenses halfway thru, and then get annoyed when I
> realize that. Having a standard will help.

The use of the present tens is stated in the GNU Coding standard.


        Stefan

Re: Your commit 7409a79

[Stephen Leake]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Ok. I often switch tenses halfway thru, and then get annoyed when I
>> realize that. Having a standard will help.
>
> The use of the present tens is stated in the GNU Coding standard.

Hmm. Not in section 6.8 Change Logs or 5.2 Commenting Your Work; I've
read those carefully. The word "tense" does not appear in the rest of
the manual (searched both the single html and ascii versions).

Can you point to a more precise reference?


5.2 does say "write complete sentences and capitalize the first word",
so we can reference that if we want it to apply to commit messages.

-- 
-- Stephe

Re: Your commit 7409a79

[Thien-Thi Nguyen]

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

Probably better to say "imperative mood".  E.g.:

- http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
- http://chris.beams.io/posts/git-commit/

I also vaguely recall something in the GCS, but now can't find it.

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

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

Re: Your commit 7409a79

[Stefan Monnier]

> Hmm. Not in section 6.8 Change Logs or 5.2 Commenting Your Work; I've
> read those carefully. The word "tense" does not appear in the rest of
> the manual (searched both the single html and ascii versions).
> Can you point to a more precise reference?

Duh, I can't find it either, even though I'm absolutely positively
certain I've seen it (and have been pointed to it) in the past.
Obviously the examples there do, but indeed the text doesn't mention it.


        Stefan

Re: Your commit 7409a79

[Stephen Leake]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Hmm. Not in section 6.8 Change Logs or 5.2 Commenting Your Work; I've
>> read those carefully. The word "tense" does not appear in the rest of
>> the manual (searched both the single html and ascii versions).
>> Can you point to a more precise reference?
>
> Duh, I can't find it either, even though I'm absolutely positively
> certain I've seen it (and have been pointed to it) in the past.
> Obviously the examples there do, but indeed the text doesn't mention
> it.

There was probably a controversy like our current one, and it got
removed as the only possible solution.

I prefer a clear statement of style; relaxing the rules can be done in
the enforcement stage.

-- 
-- Stephe

Re: Your commit 7409a79

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Duh, I can't find it either, even though I'm absolutely positively
  > certain I've seen it (and have been pointed to it) in the past.

Strange, I also remember writing about this and I don't know where it
was.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Your commit 7409a79

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

> [Present tense]
>   > Duh, I can't find it either, even though I'm absolutely positively
>   > certain I've seen it (and have been pointed to it) in the past.
>
> Strange, I also remember writing about this and I don't know where it
> was.

M-x (info "(elisp) Documentation Tips")

   • Write documentation strings in the active voice, not the passive,
     and in the present tense, not the future.  For instance, use
     “Return a list containing A and B.” instead of “A list containing A
     and B will be returned.”


-- 
David Kastrup

Re: Your commit 7409a79

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

     >   Write documentation strings in the active voice, not the passive,
     >   and in the present tense, not the future.  For instance, use
     >    Return a list containing A and B.  instead of  A list containing A
     >   and B will be returned. 

Thanks.  I should probably move the advice from there into the GNU
standards, since they are applicable to any manual.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Your commit 7409a79

[Stephen Leake]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>      >   Write documentation strings in the active voice, not the passive,
>      >   and in the present tense, not the future.  For instance, use
>      >    Return a list containing A and B.  instead of  A list containing A
>      >   and B will be returned. 
>
> Thanks.  I should probably move the advice from there into the GNU
> standards, since they are applicable to any manual.

This came up in a discussion of commit messages and Changelogs; would
you recommend active voice, present tense (not past), for those?

-- 
-- Stephe

Re: Your commit 7409a79

[Stefan Monnier]

> This came up in a discussion of commit messages and Changelogs; would
> you recommend active voice, present tense (not past), for those?

Yes.  And that's what we use.


        Stefan

Re: Your commit 7409a79

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Sun, 07 Dec 2014 16:44:41 -0600
> 
> if what you are saying is _not_ currently in CONTRIBUTE, please fix
> it (or don't say it :).

I think it's basically wrong to expect us to put every piece of advice
in some document, or forever hold our peace.  A middle ground should
exist, where we could recommend, but not insist, if the other party
feels strong about whatever issue is being discussed.

Re: Your commit 7409a79

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stephen Leake <stephen_leake@stephe-leake.org>
>> Date: Sun, 07 Dec 2014 16:44:41 -0600
>> 
>> if what you are saying is _not_ currently in CONTRIBUTE, please fix
>> it (or don't say it :).
>
> I think it's basically wrong to expect us to put every piece of advice
> in some document, or forever hold our peace.  A middle ground should
> exist, where we could recommend, but not insist, if the other party
> feels strong about whatever issue is being discussed.

"every" is a strong word, indeed.

I'll settle for "issues which have caused controversy or confusion".

And I'll have to get used to interpreting emails from core developers as
recommendations, not requirements.

-- 
-- Stephe