Re: Your commit 7409a79

[Eli Zaretskii <eliz@gnu.org>]

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