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

[Ted Zlatanov]

On Wed, 11 Jul 2018 06:32:58 +0300 Eli Zaretskii <address@hidden> wrote: 

>> From: Ted Zlatanov <address@hidden>
>> I really don't think the current format is easy for anyone, especially
>> new developers.

EZ> The format is produced mechanically by Emacs commands, so I don't see
EZ> why suddenly the format is the issue.  Maybe I interpret "format" not
EZ> the way you meant it?

Any time you force people to produce artificially structured text, it's
a tedious chore no matter how much technology you wrap around it.

Emacs does not produce the format mechanically, unless you know the
right commands. It's IMHO a pain to learn them.

EZ> It summarizes diffs, in a way, yes (and allows to add explanations if
EZ> appropriate).  I don't see that as a disadvantage: you don't always
EZ> have the ability to generate diffs (e.g., in a release tarball).

Releases communicate through NEWS and release notes.

If the users need to read the commit logs to find what files and
functions have changed since the last release, something's wrong with
the release process.

>> Anecdotally, every time I want to make a larger commit with a lot of
>> items, it feels to me like paperwork for its own sake and takes up a
>> long time.

EZ> It usually takes me a few seconds per change, so I don't see why you
EZ> feel like that.

On Tue, 10 Jul 2018 23:53:21 -0400 Stefan Monnier <address@hidden> wrote: 

SM> It also takes me very little time, but our view is strongly biased here,
SM> since we're doing it so often that we got really good at it.  For people
SM> who don't contribute often to Emacs (or other projects using a similar
SM> format) I'm sure it takes them significantly more time.

As Stefan said, it's mainly because I don't do it as often as you.
Familiarity takes time to achieve and sustain. In this case, it feels
like I'm doing work to satisfy the computer rather than to improve Emacs.

>> Here's one way to write it more concisely and make it more readable,

EZ> I'm not sure we should try to be as concise as possible in this case.
EZ> Why does the number of characters matter?  With the current format,
EZ> most of those characters are automatically generated by Emacs.

I'm advocating readability and less mechanical content, not conciseness
for its own sake.

EZ> Here are the problems with this method:

EZ>  . How do you explain in CONTRIBUTE what should and what shouldn't be
EZ>    in a log message?  We have trouble getting contributors to follow
EZ>    the current format; this one will leave us no levers to ask them to
EZ>    do it correctly, I think.  The same situation exists with comments,
EZ>    but comments we can fix by followup commits, whereas log messages
EZ>    are carved in stone once pushed.

SM> Agreed.

Log messages don't have to be carved in stone. You're justifying a human
cost with a technical side effect of the version control system.

I agree it's hard to explain what should be in a log message, but that's
because there's no perfect solution to the problem of writing down the
thought process and decisions that led to a solution. Certainly, I don't
think the current mechanical content improves that situation. It
*formalizes* the description of a specific subset of the decisions.

EZ>  . We lose information about the "several one-off implementations"
EZ>    where the changes were done.  You assume this information can
EZ>    easily be gleaned by examining the diffs, but even if the diffs are
EZ>    readily available, that assumption is not really true IME: it
EZ>    sometimes takes a non-trivial effort.

Good points. I don't think the current format makes that easy either.
Maybe there's a format that can link better and with less effort between
code and commit description in these complex cases.

EZ>  . With changes that touch a single function or a small number of
EZ>    them, your proposal will actually yield _longer_ logs, which goes
EZ>    against your intent.  Worse, it will require contributors to sit
EZ>    down and think how to describe a simple change without repeating
EZ>    the diffs, something that at least some of them will find not so
EZ>    easy, being non-native English speakers.

I think you're mixing several use cases and needs here.

Tiny changes: use the current format, it's cool.

Asking contributors to describe simple changes without repeating the
diffs: hell yeah.

Non-native English speakers: I don't see a big difference for them, they
will have a hard time regardless because Emacs is written and maintained
in English.

On Wed, 11 Jul 2018 06:44:37 +0200 Marcin Borkowski <address@hidden> wrote: 

MB> I could try to make some simple change to see where the friction is so
MB> that CONTRIBUTE can be made better, or even create a detailed technical
MB> HOWTO explaining the steps you should take to create a correct commit
MB> message.  I don't know about Ted and others, but for me that would be
MB> a tremendous help with the process which I now consider arcane and
MB> time-consuming.

EZ> FWIW, I pretty much certain that it is impossible to provide such
EZ> instructions and yet keep your goal, because what Ted actually wants
EZ> is total freedom in what text is written, and to what depth and detail
EZ> level it should describe the change.

ALSO I WANT A PONY.

OK, OK. I'm assuming there will be no change to the current format
requirements based on this thread. I'll be happily surprised if it
happens but let's be realistic. It's not a bad thing--we're having a
discussion about how to improve things. It's definitely helped me
understand Stefan and Eli's position, and we've heard from Basil and
Marcin as well.

With that assumption, ideally the current mechanical format should be
entirely pre-populated from the diff, and filled out where possible
(e.g. "added new function" "deleted symbol"). This should be a single
command "make a commit message" without a thousand options and VC or
other special interactions.

The editing mode for that format should have enough intelligence to
refresh itself (asking first, of course) if the source code is changed
underneath.

That would probably be enough to save a significant amount of time for
most non-daily contributors. Is it possible?

(This is where I'm informed it's been done already but in Haskell)

Ted