Re: ChangeLog and commit messages

[Konstantin Kharlamov <hi-angel@yandex.ru>]

On Mon, 2023-06-19 at 14:51 +0800, Po Lu wrote:
> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> 
> > Hmm, it seems it's an SVN workflow, because in git or Mercurial you can't
> > lock
> > file. I didn't have experience of working with SVN (fortunately, from what I
> > can
> > tell), but I think if I had to work with it I would use `git-svn`.

(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 😅)

> Most VCS have an option to perform locked check-outs of a file.  Git and
> Mercurial are exceptions.
> 
> > Anyway, I kind of wanted to see a commit you have troubles adding a title
> > for.
> > Judging by your first message here it's the same situation with commits to
> > Emacs, so you can drop some commit hash for example. I kind of can speculate
> > based on the general description of this SVN workflow, but it may be more
> > productive to look at specific cases where such problem arises.
> 
> If you search for ``Update Android port'' in the feature/android branch,
> you will see what I mean.

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

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.

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.

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