Re: ChangeLog and commit messages

[Po Lu]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> (actually, it turns out I did work with SVN in my first job. But it wasn't the
> only VCS we used, so I remember close to nothing about that 😅)

I'm thinking about RCS and its relatives.

> Thanks, I see this commit, I'm looking.

There are many different commits with this title.  The last change was
small, but others cannot be split up: look near the start of the branch
point for an example.

BTW, this brings up another problem with Git: it isn't possible to
determine the branch point (or even the branch name) of a revision from
the name of that revision alone.

> So… From what I can see you have two separate changes in this commit. One is
> "Only access width and height under lock", and another one… it is some
> algorithmic change in the `onLayout()`, which I didn't study too closely, but
> looking at the commit description I'm assuming it is "Send Expose upon layout
> changes if the view has grown".
>
> The problem you have here with making up a title is because you've got two
> different functional changes inside one commit. Note that you had no trouble
> writing what has changed inside the commit message. So, had you separated the
> commit to two different ones, you would've gotten a commit title for free just
> by looking at your commit message 😊
>
> When someone mixes up different functional changes, all they can give as a 
> title
> is just "Refactor foo.c" or "Rework bar" or "Fix buzz". When later looking at
> the shortlog these are pretty unhelpful titles, because it often says very
> little about what really was done in the code.

Which is the problem with the ``shortlog'' concept: detailed
descriptions of these changes should be placed in ChangeLog, and the VCS
should concentrate on tracking revisions to each file.

> It is worth noting that although Emacs does allow mixing up many changes in 
> one,
> a generally accepted good practice is to avoid that. Separating changes allows
> for the author to easier figure out what went wrong, it makes review easier, 
> and
> when one have to revert an offending commit, it makes sure that unrelated good
> changes won't be reverted together with the ones that broke something. In many
> large projects such mixing up is not allowed and in code review the author 
> will
> be asked to separate the changes.

I don't think so.  At my organization, which uses SVN, each new revision
is required to change only one file, and updates to ChangeLog are
performed separately after all edits are checked in and the
corresponding files are unlocked.  This is also the same policy that was
used by Emacs development in the CVS days, I think.

I don't know how to do this with Git, since it's not possible to update
ChangeLog separately from file check-ins.

> As an example, you can look at commit log in Mesa project¹. You can see that
> each title uniquely determines what was changed, and in many cases such 
> commits
> are short.
>
> P.S: btw, in the article² by a kernel maintainer that I referred elsewhere
> there's also a good quote on your case:
>
>> If it's not possible to describe the high level change in a few words, it is
> most likely too complex for a single commit
>
> 1: https://gitlab.freedesktop.org/mesa/mesa/-/commits/main
> 2: http://who-t.blogspot.com/2009/12/on-commit-messages.html

I've read the article, and I don't agree.