Re: Your commit 7409a79

[Stephen Leake]

Eli Zaretskii <address@hidden> writes:

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

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 <address@hidden>, 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 address@hidden