ChangeLog and commit messages

ChangeLog and commit messages

[Po Lu]

I find myself often frustrated that Git requires a commit title.  In
such a title, committers are expected to summarize in detail changes to
dozens of different functions in less than 74 characters of text.

Normally, the place for such descriptions would be in ChangeLog and not
the commit message title.  Would it be possible to allow writing commit
messages consisting solely of ChangeLog, forgoing the commit title
entirely?

Thanks.

Re: ChangeLog and commit messages

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Date: Sun, 18 Jun 2023 15:14:50 +0800
> 
> I find myself often frustrated that Git requires a commit title.  In
> such a title, committers are expected to summarize in detail changes to
> dozens of different functions in less than 74 characters of text.
> 
> Normally, the place for such descriptions would be in ChangeLog and not
> the commit message title.  Would it be possible to allow writing commit
> messages consisting solely of ChangeLog, forgoing the commit title
> entirely?

How would that work, exactly?  Do you want to switch back to Bazaar or
CVS?

OTOH, I don't really understand the difficulties of summarizing a
commit in a single line.  I rarely if ever have problems with that.

Re: ChangeLog and commit messages

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> How would that work, exactly?  Do you want to switch back to Bazaar or
> CVS?

No, that wouldn't be necessary.  One idea I have is to allow writing:

  ** no title **

in commit messages, and to avoid placing such titles in the generated
ChangeLog.

> OTOH, I don't really understand the difficulties of summarizing a
> commit in a single line.  I rarely if ever have problems with that.

I guess our experiences differ wrt this.

Thanks.

Re: ChangeLog and commit messages

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 15:41:28 +0800
> 
> One idea I have is to allow writing:
> 
>   ** no title **
> 
> in commit messages, and to avoid placing such titles in the generated
> ChangeLog.

If you do that, it will break "git log --pretty=oneline" and Emacs
features such as "C-x v L".

There's a reason why we require a meaningful heading line.  It isn't
arbitrary, and its main purpose is not for ChangeLog at all.

Re: ChangeLog and commit messages

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 15:41 +0800, Po Lu wrote:
> > OTOH, I don't really understand the difficulties of summarizing a
> > commit in a single line.  I rarely if ever have problems with that.
> 
> I guess our experiences differ wrt this.

Could you please describe some example of when this happens? As someone who has
contributed to dozens of projects, I can say there's likely something odd in
your workflow. If you provide details on where and why you have problems, I
think I could give suggestions for how to avoid that.

Re: ChangeLog and commit messages

[Po Lu]

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

> Could you please describe some example of when this happens? As
> someone who has contributed to dozens of projects, I can say there's
> likely something odd in your workflow. If you provide details on where
> and why you have problems, I think I could give suggestions for how to
> avoid that.

When I'm working on a file, I lock (using the VCS) the files which I
need to edit.  Then, as I work, I type C-x 4 a and describe the changes
being made to each function.  Finally, I check in the changes made to
those locked files, and update ChangeLog.

Typically, those check-ins are made at the end of the workday, but
sometimes sooner if another developer complains that a file he wishes to
edit is locked.

Re: ChangeLog and commit messages

[Konstantin Kharlamov]

On Mon, 2023-06-19 at 08:48 +0800, Po Lu wrote:
> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> 
> > Could you please describe some example of when this happens? As
> > someone who has contributed to dozens of projects, I can say there's
> > likely something odd in your workflow. If you provide details on where
> > and why you have problems, I think I could give suggestions for how to
> > avoid that.
> 
> When I'm working on a file, I lock (using the VCS) the files which I
> need to edit.  Then, as I work, I type C-x 4 a and describe the changes
> being made to each function.  Finally, I check in the changes made to
> those locked files, and update ChangeLog.
> 
> Typically, those check-ins are made at the end of the workday, but
> sometimes sooner if another developer complains that a file he wishes to
> edit is locked.

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

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.

Re: ChangeLog and commit messages

[Po Lu]

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

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.

Re: ChangeLog and commit messages

[Konstantin Kharlamov]

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

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.

Re: ChangeLog and commit messages

[Dmitry Gutov]

On 19/06/2023 13:10, Po Lu wrote:
> 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.

Sounds like your organization uses a fairly antiquated workflow.

Luckily, we're a few steps ahead now in Emacs development.

Re: ChangeLog and commit messages

[Eli Zaretskii]

> Date: Mon, 19 Jun 2023 14:57:23 +0300
> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
> From: Dmitry Gutov <dmitry@gutov.dev>
> 
> On 19/06/2023 13:10, Po Lu wrote:
> > 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.
> 
> Sounds like your organization uses a fairly antiquated workflow.
> 
> Luckily, we're a few steps ahead now in Emacs development.

Was this really an opinion worthy of making public?  How is it
supposed to be helpful for a serious discussion to derogate the
participants?  The man was asked to describe his use case, so he did
it.  It makes no sense to reprimand him for telling us what we asked
to hear.

Re: ChangeLog and commit messages

[Dmitry Gutov]

On 19/06/2023 19:59, Eli Zaretskii wrote:
>> Date: Mon, 19 Jun 2023 14:57:23 +0300
>> Cc: Eli Zaretskii<eliz@gnu.org>,emacs-devel@gnu.org
>> From: Dmitry Gutov<dmitry@gutov.dev>
>>
>> On 19/06/2023 13:10, Po Lu wrote:
>>> 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.
>> Sounds like your organization uses a fairly antiquated workflow.
>>
>> Luckily, we're a few steps ahead now in Emacs development.
> Was this really an opinion worthy of making public?  How is it
> supposed to be helpful for a serious discussion to derogate the
> participants?

I wasn't talking about the participants (who might well all be competent 
programmers), just about the workflow.

But the phrasing was not great, I suppose. Apologies.

> The man was asked to describe his use case, so he did
> it.  It makes no sense to reprimand him for telling us what we asked
> to hear.

That's not all, though. He expressed a general opinion about what should 
go into commit messages, and what should go into ChangeLog:

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

Re: ChangeLog and commit messages

[Konstantin Kharlamov]

(I apologise in advance, I likely to be slow to answer)

On Mon, 2023-06-19 at 18:10 +0800, Po Lu wrote:
> 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.

Okay, so, it might be more efficient if you point me at a specific commit you
have in mind. Does this one work, for example?
https://git.savannah.gnu.org/cgit/emacs.git/commit/?h=feature/android&id=5b4dea0fc781fe40548e7b58fe5bd201a05f3913

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

Oh, yeah. I imagine this could come in handy, for example to remove merged local
branches. I have so many at work, but it's often very hard to automatically
determine which ones had been merged, because commits ID often change upon merge
through rebase.

OTOH, if a project have many thousands of commits, like Linux kernel, this may
become a problem as your name may clash with another one for legitimate
reasons. And I also had on a few occasions multiple branches where commit with
the same title had different content (again, for legitimate reasons: I was
experimenting with different approaches, and only one of these commits made it
upstream in the end. Final commit likely had title changed, but I still have
other "testing" commits locally).

So… I would say whether it's better is debatable.

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

Sorry, I may be missing something. You said "this is the problem" which implies
the problem should be obvious from the context, but I struggle to see it. Some
additional details may help.

We can discuss a workflow with placing entries to a Changelog file as compared
to usual git workflow, if you want. I'm just not sure if you're interested in
that.

> > 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 am afraid such workflow would break both bisection and the ability to see
what's changed by other developers. This is because in many cases a change
affects more than one file. For example: when you change a function helper in C,
you may need to edit a header and all C files where it's declared. If you create
separate revision for each of these changes, this will α) break compilation in
each of these revisions till the last one, and β) will make reading the log
(either for code review or for other purposes) harder, because the context of
the change is no longer in the same commit.

FWIW, at my work after stumbling upon a few situations where some commits
couldn't be compiled within same series, we ended up adding a CI check that
tests each individual commit for compilation. So people can't commit a revision
that does not pass compilation.

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

I might be missing something here, because I'm not sure what is not possible
here. I mean, you can create a separate commit for each individual file. And you
can edit Changelog there as well, or you can avoid editing it.

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

If you have any specific points, we can discuss them, if you want of course.

Re: ChangeLog and commit messages

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  emacs-devel@gnu.org
> Date: Mon, 19 Jun 2023 14:51:53 +0800
> 
> 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`.
> 
> 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.

If your problems are with the feature branch, then I think you are
making your life harder than it needs to be.  Our conventions for
formatting commit log messages don't apply to feature branches.  On
feature branches, the developers are free to format the log messages
as they see fit; the only log message that matters is the one for the
merge-commit which lands the feature branch on master (which you have
to create by hand anyway).

The upshot of all this is that while you are working on a feature
branch:

  . you can use short single-line note-like log messages, which might
    be unclear to anyone but yourself
  . you should generally commit each time when you finish some
    meaningful changeset, so that it could be later reverted without
    complications -- this goes well with short log messages
  . it is futile to use "C-x 4 a"-style log messages, especially for
    changes in files or in functions the branch adds, because in the
    final commit log we only need to see "foo: New file"

This leaves you with the need to come up with a commit log for when
the branch is landed.  That might sometimes be a large job, but it
will be much smaller than the sum total of what you do now.  Moreover,
what you do now will not help you avoid this job, because we do
require3 a meaningful summary log message for when the branch is
merged.

Re: ChangeLog and commit messages

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> If your problems are with the feature branch, then I think you are
> making your life harder than it needs to be.  Our conventions for
> formatting commit log messages don't apply to feature branches.  On
> feature branches, the developers are free to format the log messages
> as they see fit; the only log message that matters is the one for the
> merge-commit which lands the feature branch on master (which you have
> to create by hand anyway).
>
> The upshot of all this is that while you are working on a feature
> branch:
>
>   . you can use short single-line note-like log messages, which might
>     be unclear to anyone but yourself
>   . you should generally commit each time when you finish some
>     meaningful changeset, so that it could be later reverted without
>     complications -- this goes well with short log messages
>   . it is futile to use "C-x 4 a"-style log messages, especially for
>     changes in files or in functions the branch adds, because in the
>     final commit log we only need to see "foo: New file"
>
> This leaves you with the need to come up with a commit log for when
> the branch is landed.  That might sometimes be a large job, but it
> will be much smaller than the sum total of what you do now.  Moreover,
> what you do now will not help you avoid this job, because we do
> require3 a meaningful summary log message for when the branch is
> merged.

OK, thanks for explaining.

Re: ChangeLog and commit messages

[Sean Whitton]

Hello,

On Mon 19 Jun 2023 at 07:33PM +03, Eli Zaretskii wrote:

> If your problems are with the feature branch, then I think you are
> making your life harder than it needs to be.  Our conventions for
> formatting commit log messages don't apply to feature branches.  On
> feature branches, the developers are free to format the log messages
> as they see fit; the only log message that matters is the one for the
> merge-commit which lands the feature branch on master (which you have
> to create by hand anyway).
>
> The upshot of all this is that while you are working on a feature
> branch:
>
>   . you can use short single-line note-like log messages, which might
>     be unclear to anyone but yourself
>   . you should generally commit each time when you finish some
>     meaningful changeset, so that it could be later reverted without
>     complications -- this goes well with short log messages
>   . it is futile to use "C-x 4 a"-style log messages, especially for
>     changes in files or in functions the branch adds, because in the
>     final commit log we only need to see "foo: New file"

Is this written down somewhere?  I had no idea about it.  If I'd
recently started a feature branch, I'd likely have been carefully
formatting my commits, for no good reason.

-- 
Sean Whitton

Re: ChangeLog and commit messages

[Eli Zaretskii]

> From: Sean Whitton <spwhitton@spwhitton.name>
> Cc: Po Lu <luangruo@yahoo.com>,  hi-angel@yandex.ru,  emacs-devel@gnu.org
> Date: Fri, 23 Jun 2023 07:50:52 +0100
> 
> Hello,
> 
> On Mon 19 Jun 2023 at 07:33PM +03, Eli Zaretskii wrote:
> 
> > If your problems are with the feature branch, then I think you are
> > making your life harder than it needs to be.  Our conventions for
> > formatting commit log messages don't apply to feature branches.  On
> > feature branches, the developers are free to format the log messages
> > as they see fit; the only log message that matters is the one for the
> > merge-commit which lands the feature branch on master (which you have
> > to create by hand anyway).
> >
> > The upshot of all this is that while you are working on a feature
> > branch:
> >
> >   . you can use short single-line note-like log messages, which might
> >     be unclear to anyone but yourself
> >   . you should generally commit each time when you finish some
> >     meaningful changeset, so that it could be later reverted without
> >     complications -- this goes well with short log messages
> >   . it is futile to use "C-x 4 a"-style log messages, especially for
> >     changes in files or in functions the branch adds, because in the
> >     final commit log we only need to see "foo: New file"
> 
> Is this written down somewhere?

Not that I know of, no.

> I had no idea about it.

Did you work on feature branches of the Emacs Git repository?  Very
few people did or do, so having this in the documentation for the
benefit of a very few sounds un-economical.  I won't object to having
this in some place in admin/notes if someone finds that useful, but
please note that what I wrote is by no means agreed upon by everyone:
opinions vary widely and wildly on what are the best practices of
working on branches, starting from the merge vs rebase issue (if one
uses rebase, the log messages of intermediate commits disappear
anyway).

> If I'd recently started a feature branch, I'd likely have been
> carefully formatting my commits, for no good reason.

Which is why I posted the above.  Now you know.

Re: ChangeLog and commit messages

[Sean Whitton]

Hello,

On Fri 23 Jun 2023 at 10:16am +03, Eli Zaretskii wrote:

>> From: Sean Whitton <spwhitton@spwhitton.name>
>> Cc: Po Lu <luangruo@yahoo.com>,  hi-angel@yandex.ru,  emacs-devel@gnu.org
>> Date: Fri, 23 Jun 2023 07:50:52 +0100
>>
>> On Mon 19 Jun 2023 at 07:33PM +03, Eli Zaretskii wrote:
>>
>> > If your problems are with the feature branch, then I think you are
>> > making your life harder than it needs to be.  Our conventions for
>> > formatting commit log messages don't apply to feature branches.  On
>> > feature branches, the developers are free to format the log messages
>> > as they see fit; the only log message that matters is the one for the
>> > merge-commit which lands the feature branch on master (which you have
>> > to create by hand anyway).
>> >
>> > The upshot of all this is that while you are working on a feature
>> > branch:
>> >
>> >   . you can use short single-line note-like log messages, which might
>> >     be unclear to anyone but yourself
>> >   . you should generally commit each time when you finish some
>> >     meaningful changeset, so that it could be later reverted without
>> >     complications -- this goes well with short log messages
>> >   . it is futile to use "C-x 4 a"-style log messages, especially for
>> >     changes in files or in functions the branch adds, because in the
>> >     final commit log we only need to see "foo: New file"
>>
>> Is this written down somewhere?
>
> Not that I know of, no.
>
>> I had no idea about it.
>
> Did you work on feature branches of the Emacs Git repository?  Very
> few people did or do, so having this in the documentation for the
> benefit of a very few sounds un-economical.  I won't object to having
> this in some place in admin/notes [...]

Finally installed some additional text for this under admin/notes/.

-- 
Sean Whitton

Re: ChangeLog and commit messages

[Sean Whitton]

Hello,

On Sun 18 Jun 2023 at 03:14PM +08, Po Lu wrote:

> I find myself often frustrated that Git requires a commit title.  In
> such a title, committers are expected to summarize in detail changes to
> dozens of different functions in less than 74 characters of text.

Yes, it doesn't fit well with Emacs changelog practices ...

> Normally, the place for such descriptions would be in ChangeLog and
> not the commit message title.  Would it be possible to allow writing
> commit messages consisting solely of ChangeLog, forgoing the commit
> title entirely?

... but this renders C-x v L so much less useful, and anyone who uses
git for other projects will be used to using that view of things a lot.

-- 
Sean Whitton

Re: ChangeLog and commit messages

[Dmitry Gutov]

On 18/06/2023 10:14, Po Lu wrote:
> Would it be possible to allow writing commit
> messages consisting solely of ChangeLog, forgoing the commit title
> entirely?

Commit summaries are often useful to understand whether one needs to 
write the subsequent message and the diff, or can skip it more or less 
safely.

For example, it's most welcome when the summary mentions the subsystem 
it's acting on (e.g. android/ns/python/org/irc/url/bidi/font-lock/...).

Re: ChangeLog and commit messages

[Jose E. Marchesi]

> I find myself often frustrated that Git requires a commit title.  In
> such a title, committers are expected to summarize in detail changes to
> dozens of different functions in less than 74 characters of text.

When I find myself in that situation, I interpret it as a sign that the
problem is better (more naturally) handled by several commits instead of
just one.

> Normally, the place for such descriptions would be in ChangeLog and not
> the commit message title.  Would it be possible to allow writing commit
> messages consisting solely of ChangeLog, forgoing the commit title
> entirely?

I wouldn't recommend that.  It makes `git log --oneline' useless.

Re: ChangeLog and commit messages

[Bruno Haible]

Po Lu wrote:
> I find myself often frustrated that Git requires a commit title.  In
> such a title, committers are expected to summarize in detail changes to
> dozens of different functions in less than 74 characters of text.

That's a feature, not a bug.

The commit title has benefits for the co-developers and for yourself, the
committer. Namely:

* If I am a co-developer, I want to know
  - the purpose of the change,
  - whether I can expect my existing tests or usage to continue working, or
    whether it will break,
  - whether I have the opportunity to extend my tests / change my usage.

For you, the committer, simply think of someone else asking you "what is
the point of this change?".

Thinking about this title for 30 seconds gives you the opportunity to
  - detect when you are about to commit two unrelated things (e.g. a bug fix
    and a new feature)
  - if it's a new feature: question yourself whether you have been including
    necessary documentation changes and/or a NEWS entry.

Bruno