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

[Eli Zaretskii]

> From: Radon Rosborough <address@hidden>
> Date: Thu, 12 Jul 2018 22:33:13 -0600
> Cc: Ted Zlatanov <address@hidden>, Lars Ingebrigtsen <address@hidden>, 
> emacs-devel <address@hidden>
> 
> > 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.

Sorry, I've misinterpreted what you wrote to mean that magit's docs
don't cover the features we need.  If the docs do cover that, then
yes, a short reference to them, as in "If you use magit, set
this-and-that variable and use such-and-such commands" would be a
welcome addition to CONTRIBUTE.

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

At the risk of sounding like a broken record, may I suggest to provide
a specific critique of the relevant CONTRIBUTE parts?  Like a patch,
or a quotation followed by an explanation why you think that
particular text is unclear or missing something?

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

That might be an interesting discussion, but I doubt it belongs to
this list.  GNU projects have several peculiar requirements, like
copyright assignments and adherence to the GNU Coding Standards
document, which are not specific to Emacs, and against which people
sometimes complain, because other projects don't bother with those.
Discussing that here is not useful.

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

I want to see log entries that mention the functions/variables which
were changed, and a high-level description of the changes, with
motivation for the changes where appropriate.  (Note that a pointer to
a bug number can usually serve instead of many words, because the
discussion of the bug includes a lot of useful information.)  The
exact form is much less important to me, except that changelog-mode
already makes that available in a format that is well known.  But IMO
that format in itself is not sacred; the information it provides is.

> Personally, what I want to see in commit messages is a properly
> formatted summary line

Actually, I find the summary line to be a nuisance in too many cases.
>From my POV, it's something we must do because Git more-or-less
requires that, but I find myself thinking about it for too long in
some cases, and OTOH some header lines I see in the repository are
(non-funny) jokes.  I grind my teeth and adhere to that convention,
but I don't like it.  This is the other face of dropping ChangeLog:
there was never a requirement for a header line in ChangeLog entries,
so I provided one when that made sense, and didn't when it didn't.
Now I _must_ provide it unless the log entry is short enough to serve
as its own header line (which is sometimes downright impossible
because the file name and the function name are already too long).

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

It's the "anything important to know about the change that can't be
put in comments" part that I'm worried about.  How do you tell
contributors clearly and concisely how to achieve that, if the idea is
that they can write anything they think is right there?

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

It's not really a seven-line list, because the important part is the
explanations after that.  Let me rephrase: it's too long to put in
CONTRIBUTE, and it's too long to ask contributors to read before they
submit a patch.

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

Propose specific changes that will make the job easier without losing
information.  Explain, and ask others to explain, _why_ what we
currently require is so much harder than the alternatives (and limit
the valid alternatives to those that don't lose information).  Submit
patches to commands that will make the job easier.  Etc. etc.

> My position is based on the belief that the current format makes it
> harder for new contributors than a more open format.

If there is a reasonable way to make it easier without losing valuable
information, sure, we'd like to do that.  Otherwise, it's just one of
those cases where one needs to pay a (IMO small) fee to participate in
a project.  Because making contributions easier is not the only valid
motivation in setting up our procedures, there are certain
considerations that we must observe.