Re: git history tracking across renames (and emacs support)

[Radon Rosborough <radon.neon@gmail.com>]

> Is it really an issue with magit? And if it is, why isn't it
> documented in magit's documentation?

In my opinion, it doesn't really make sense for Magit, a
general-purpose Git frontend, to document the specific contribution
guidelines for GNU projects.

Sure, Magit should document the functionality it provides, and I
believe it does provide ChangeLog-related functionality. But in that
case, the Emacs CONTRIBUTE should most assuredly link to that
documentation. It can't simply say "please figure it out yourself"!
Since GNU projects are using a nonstandard commit message formatting
from the perspective of the rest of the world, I think the burden is
on them to tell contributors about that format and how to produce it
(if indeed the format is too burdensome to write by hand, which I
believe the ChangeLog format is).

>> As soon as I am linked to documentation about editing
>> ChangeLog files, I will assume I've gone astray, unless it's explained
>> why editing ChangeLog files is necessary in order to generate a commit
>> message.
>
> I don't understand why. How about providing detailed critique of
> what CONTRIBUTE says under "Generating ChangeLog entries"?

On re-reading very carefully, I see that I read "write ChangeLog
entries" as an operation that one would do when creating a ChangeLog
file, whereas it was meant more generally.

So, yes, the misunderstanding is my fault. However, I think it would
be much clearer if there were actual, literal step-by-step
instructions on how to go from a working directory with some changes
in it to a properly formatted commit. Directing people to pore through
the manual just so they can commit to Emacs seems a bit burdensome to
me; isn't there a reason we have CONTRIBUTE? To make contributing as
easy as possible?

I'm sure somebody will say that I am just being lazy. But the fact
remains that Emacs is much harder to contribute to than other
open-source projects, because of things like this.

>> It seems to me that ChangeLog is a "GNU thing". As are mailing
>> lists, avoidance of GitLab, using debbugs, etc.
>
> Well, we are talking about Emacs, and Emacs will always be a GNU
> project.

*cough* https://github.com/Wilfred/remacs *cough*

But seriously though, just because GNU projects usually have
ChangeLogs doesn't mean that ChangeLogs are a good idea. If they are
such a good idea, then why don't any other projects have them?

> Nevertheless, log messages provided by contributors are pretty close
> to what I'd like to see, after a couple of initial submissions,
> where we generally need to point out some minor nits.

But what do you want to see? Auto-generated ChangeLog entries? If
that's really what you want, then it sounds like you aren't open to
any other format.

Personally, what I want to see in commit messages is a properly
formatted summary line, links to any related bug reports, and an
explanation of anything important to know about the change that can't
be put in comments. These things could be included or not regardless
of whether ChangeLog format is used. They are what *I* want to see;
what do you want to see?

> > I think the blog does a much better job of getting across its
> > information clearly, concisely, and understandably:
>
> It's too long, IMO.

Surely the seven-line bullet-point list is not too long, is it?
Honestly, the rest of the article is just embellishment. If you
*really* want a shorter article, there are plenty of others that say
essentially the same thing in different words (because, as I've said,
essentially every open-source project uses these guidelines as a
baseline):

* https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53
* https://github.com/erlang/otp/wiki/writing-good-commit-messages
* https://medium.com/@steveamaza/how-to-write-a-proper-git-commit-message-e028865e5791

>> Plus, everybody knows this already, since virtually every open-source
>> project follows more or less these guidelines for commit messages.
>
> If so, why would someone need to write a blog, and why would we need
> to point to it? Evidently not everybody knows that.

I said "everybody knows" in the same sense that I say "everyone knows
you're not supposed to check the binaries into Git". Like, sure, there
are people who don't know, but in that case it's pretty much on them
because this is a really basic thing that you just have to learn if
you want to do open-source software development. As a corollary, if
"everybody knows" something, then we should certainly mention it, but
we shouldn't consider it burdensome to expect people to learn about it
if they didn't already know.

> If the proposal is to let people write what they want, then I don't
> think I'd agree, for reasons I tried to explain.

That's unfortunate. What would change your mind?

My position is based on the belief that the current format makes it
harder for new contributors than a more open format. If potential new
contributors to Emacs were to tell me they prefer the current format,
then that would change *my* mind.