Re: ChangeLog generation

[Frank Terbeck <ft@xxxxxxxxxxxxxxxxxxx>]

Bart Schaefer wrote:
[...]
> Hrm.  This is nice work and a pretty good compromise, but just in the
> course of looking through the sample output you included on that web
> page, there appear several cases where the existing ChangeLog is
> actually more accurate (thanks to having been repaired) than the commit
> log entries from which it would be "regenerated" by the script.
>
> One of my pet peeves with automating things in this way is that it often
> means typographical errors get enshrined for eternity, sometimes with
> confusing results when someone else goes looking through the logs.
> (Don't get me started on the inability to edit comments in bugzilla.)

Well, with the script, you can change the generated text, all you want.
Just leave the hash-sums of the individual entries intact. They are used
by the script were to pick up generation in the next run.

The old text in the generated changelog is not re-generated and manual
changes will be kept and not overridden. If that would happen, that
would be a bug.

I do hate typos, too. But once a typo is in a commit message on the
central repository, you can't fix it in the commit message anymore
(well, you can, but you'd change history and all hash-sums after your
typo fix would be changed - that's something the git community advocates
against, because it screws everybody who has got work that's based on
the old tree).

The way to prevent that, is this: You usually prepare patches to the
mailing list using `git format-patch' (which you can conveniently send
by using `git send-email'). Those patches contain the complete commit
message, however detailed it may be.

Reviewers should try to spot typos, so the author can fix them in
his/her own local repository. All parts of a local repository, that are
not in the central repository, yet, can be changed over and over again
until the author is satisfied with the result.


If a typo still makes it to the changelog (note, that the script only
picks up the first like of a git-commit message¹ - the subject, so to
speak), you can fix it up manually; because generation is done
incrementally, like I said above.

> Also ... I'm not that familiar with how git organizes commits, i.e.,
> what determines the list/of/change/files for a particular hash-sum.

Generally speaking, git doesn't track files. It tracks the content of
the files. And thus changes are recorded with the whole tree in mind. As
change-sets.

I think that makes very much sense. In a commit message you'd then
describe the change that is introduced by all the changes to all touched
files. A commit should only cover one such change, like a new feature or
option.

I'm also a fan of long detailed commit messages. ;)

> In an ideal world the commit entry for a given file would discuss only
> the changes relevant to that specific file, even if there were a bunch
> of changed files that should all be considered as a group in that the
> changes to one don't make sense without the changes to another.  I
> have often found myself doing several "cvs commit" to cover each subset
> of the files that were edited, and then a single commit of ChangeLog
> with a composite description to give the context in which all the other
> commits were made.
>
> Is anything like that possible here?

Sure. You can mark a single line from a set of changes across multiple
files for commit and just commit that. Or a single hunk. Or indeed a
single file. Git offers full control over what's going into the next
commit and what doesn't.

And sometimes, when I didn't pay attention and make many unrelated
changes, I go fire up "git gui" and dissect my changes into logical,
atomic commits, to keep a project's history useful. (Having atomic
commits makes it easy to revert changes, too, if that would be needed at
some point in the future.)

> At the very least we're going to need to come up with a new convention
> for the commit logs so that the mailing list article IDs are not lost.

Like I said in my reply to Peter, I think this is a job for `git-notes'.


Regards, Frank


¹ A quick note about git's commit message convention: A message starts
with a short descriptive one-line title followed by an *empty* line,
followed by a body of arbitrary length. And git's `format-patch'
actually puts that title line into the generated email's Subject:
header, the lengthy body obviously goes into the email's body.