Commit messages and the move to git

classic Classic list List threaded Threaded
104 messages Options
1234 ... 6
Reply | Threaded
Open this post in threaded view
|

Commit messages and the move to git

Richard Earnshaw (lists)
With the move to git fairly imminent now it would be nice if we could
agree on a more git-friendly style of commit messages; and, ideally,
start using them now so that the converted repository can benefit from this.

Some tools, particularly gitk or git log --oneline, can use one-line
summaries from a commit's log message when listing commits.  It would be
nice if we could start adopting a style that is compatible with this, so
that in future commits are summarized in a useful way.  Unfortunately,
some of our existing commits show no useful information with tools like
this.

Eg.

git log --oneline
2b70dbd64b5 (HEAD -> master, origin/trunk, origin/master, origin/HEAD)
2019-11-01  Kewen Lin  <[hidden email]>
29f4f5f13b9 [C++ PATCH] cleanup check_field_decls
0f931fb75ae 2019-11-01  Kewen Lin  <[hidden email]>
e9c4da22199 OpenMP] use_device_addr/use_device_ptr with Fortran
allocatable/pointer arrays
377311a90fa 2019-11-01  Kewen Lin  <[hidden email]>
cc286dd8517 Daily bump.
8e87e30df8d Regenerate libstdc++ HTML docs
fad04d507e0 Add remaining changes from P1065R2 "constexpr INVOKE"
d5e4b5a17de Partial implementation of C++20 of <ranges> header
345d712f776 Test --help=common for full sentences
a737cc23c15     PR preprocessor/92296   * internal.h (struct
def_pragma_macro): Add is_builtin bitfield.
(_cpp_restore_special_builtin): Declare.        * init.c
(_cpp_restore_special_builtin): New function.  * directives.c
(do_pragma_push_macro): For NT_BUILTIN_MACRO     set is_builtin and
don't try to grab definition.        (cpp_pop_definition): Use
_cpp_restore_special_builtin to restore       builtin macros.
e9c843f92f6 2019-10-31  Jozef Lawrynowicz  <[hidden email]>
d7069e154ee [AArch64] Fix g++.target/aarch64/sve/vcond_1_run.C
ae5f034c085 [AArch64] Split gcc.target/aarch64/sve/vcond_4*

As you can see, some of these are useful and give a good summary of the
patch, others only tell me who committed the patch, which is less than
useful.  In other cases almost the entire ChangeLog entry gets printed
because there is no blank line to tell git where the end of the summary
lies.

The normal convention in git is that the one line summary is essentially
the subject line of the email message that describes the patch and is
then followed by a blank line before the body of the commit message.

R.
Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Arnaud Charlet
> With the move to git fairly imminent now it would be nice if we
> could agree on a more git-friendly style of commit messages; and,
> ideally, start using them now so that the converted repository can
> benefit from this.
>
> Some tools, particularly gitk or git log --oneline, can use one-line
> summaries from a commit's log message when listing commits.  It
> would be nice if we could start adopting a style that is compatible
> with this, so that in future commits are summarized in a useful way.
> Unfortunately, some of our existing commits show no useful
> information with tools like this.

Strongly seconded. FWIW we've done that for a while in the gcc/ada directory
already since we're using GIT internally on GCC and GNAT sources.

Arno
Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Martin Jambor-3
In reply to this post by Richard Earnshaw (lists)
On Mon, Nov 04 2019, Richard Earnshaw (lists) wrote:
> Some tools, particularly gitk or git log --oneline, can use one-line
> summaries from a commit's log message when listing commits.  It would be
> nice if we could start adopting a style that is compatible with this, so
> that in future commits are summarized in a useful way.

...

> The normal convention in git is that the one line summary is essentially
> the subject line of the email message that describes the patch and is
> then followed by a blank line before the body of the commit message.
>

I wholeheartedly agree.  Thanks to everyone already doing this and
everyone else, please just start, adding a summary line takes just
minimal effort.

Martin
Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Jeff Law
In reply to this post by Richard Earnshaw (lists)
On 11/4/19 3:29 AM, Richard Earnshaw (lists) wrote:

> With the move to git fairly imminent now it would be nice if we could
> agree on a more git-friendly style of commit messages; and, ideally,
> start using them now so that the converted repository can benefit from
> this.
>
> Some tools, particularly gitk or git log --oneline, can use one-line
> summaries from a commit's log message when listing commits.  It would be
> nice if we could start adopting a style that is compatible with this, so
> that in future commits are summarized in a useful way.  Unfortunately,
> some of our existing commits show no useful information with tools like
> this.
I'd suggest we sync policy with glibc.  They're further along on the
ChangeLog issues.  Whatever they do in this space we should follow --
aren't we going to be using some of their hooks/scripts?

jeff

Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Richard Earnshaw (lists)
On 04/11/2019 16:04, Jeff Law wrote:

> On 11/4/19 3:29 AM, Richard Earnshaw (lists) wrote:
>> With the move to git fairly imminent now it would be nice if we could
>> agree on a more git-friendly style of commit messages; and, ideally,
>> start using them now so that the converted repository can benefit from
>> this.
>>
>> Some tools, particularly gitk or git log --oneline, can use one-line
>> summaries from a commit's log message when listing commits.  It would be
>> nice if we could start adopting a style that is compatible with this, so
>> that in future commits are summarized in a useful way.  Unfortunately,
>> some of our existing commits show no useful information with tools like
>> this.
> I'd suggest we sync policy with glibc.  They're further along on the
> ChangeLog issues.  Whatever they do in this space we should follow --
> aren't we going to be using some of their hooks/scripts?
>
> jeff
>

I wouldn't object to that.  But then, it's largely what I'm asking for,
with a few minor details.

https://sourceware.org/glibc/wiki/Contribution%20checklist#Contribution_Email_Subject_Line

Seems to set out the rules.

I think we'd probably want to keep PRnnnnn rather than switch to BZ
#nnnnnn, but otherwise there's nothing I'd object to.

It looks like, from a quick look at
https://sourceware.org/ml/glibc-cvs/2019-q4/ that the email subject
lines are largely what is used for the summary commits.

R.
Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Jonathan Wakely-4
In reply to this post by Richard Earnshaw (lists)
On Mon, 4 Nov 2019 at 10:29, Richard Earnshaw (lists)
<[hidden email]> wrote:

>
> With the move to git fairly imminent now it would be nice if we could
> agree on a more git-friendly style of commit messages; and, ideally,
> start using them now so that the converted repository can benefit from this.
>
> Some tools, particularly gitk or git log --oneline, can use one-line
> summaries from a commit's log message when listing commits.  It would be
> nice if we could start adopting a style that is compatible with this, so
> that in future commits are summarized in a useful way.  Unfortunately,
> some of our existing commits show no useful information with tools like
> this.
>
> Eg.
>
> git log --oneline
> 2b70dbd64b5 (HEAD -> master, origin/trunk, origin/master, origin/HEAD)
> 2019-11-01  Kewen Lin  <[hidden email]>
> 29f4f5f13b9 [C++ PATCH] cleanup check_field_decls
> 0f931fb75ae 2019-11-01  Kewen Lin  <[hidden email]>
> e9c4da22199 OpenMP] use_device_addr/use_device_ptr with Fortran
> allocatable/pointer arrays
> 377311a90fa 2019-11-01  Kewen Lin  <[hidden email]>
> cc286dd8517 Daily bump.
> 8e87e30df8d Regenerate libstdc++ HTML docs
> fad04d507e0 Add remaining changes from P1065R2 "constexpr INVOKE"
> d5e4b5a17de Partial implementation of C++20 of <ranges> header
> 345d712f776 Test --help=common for full sentences
> a737cc23c15     PR preprocessor/92296   * internal.h (struct
> def_pragma_macro): Add is_builtin bitfield.
> (_cpp_restore_special_builtin): Declare.        * init.c
> (_cpp_restore_special_builtin): New function.  * directives.c
> (do_pragma_push_macro): For NT_BUILTIN_MACRO     set is_builtin and
> don't try to grab definition.        (cpp_pop_definition): Use
> _cpp_restore_special_builtin to restore       builtin macros.
> e9c843f92f6 2019-10-31  Jozef Lawrynowicz  <[hidden email]>
> d7069e154ee [AArch64] Fix g++.target/aarch64/sve/vcond_1_run.C
> ae5f034c085 [AArch64] Split gcc.target/aarch64/sve/vcond_4*
>
> As you can see, some of these are useful and give a good summary of the
> patch, others only tell me who committed the patch, which is less than
> useful.  In other cases almost the entire ChangeLog entry gets printed
> because there is no blank line to tell git where the end of the summary
> lies.
>
> The normal convention in git is that the one line summary is essentially
> the subject line of the email message that describes the patch and is
> then followed by a blank line before the body of the commit message.

I've already proposed a more specific format for libstdc++:
https://gcc.gnu.org/ml/libstdc++/2019-09/msg00122.html
Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Richard Earnshaw (lists)
On 04/11/2019 16:19, Jonathan Wakely wrote:

> On Mon, 4 Nov 2019 at 10:29, Richard Earnshaw (lists)
> <[hidden email]> wrote:
>>
>> With the move to git fairly imminent now it would be nice if we could
>> agree on a more git-friendly style of commit messages; and, ideally,
>> start using them now so that the converted repository can benefit from this.
>>
>> Some tools, particularly gitk or git log --oneline, can use one-line
>> summaries from a commit's log message when listing commits.  It would be
>> nice if we could start adopting a style that is compatible with this, so
>> that in future commits are summarized in a useful way.  Unfortunately,
>> some of our existing commits show no useful information with tools like
>> this.
>>
>> Eg.
>>
>> git log --oneline
>> 2b70dbd64b5 (HEAD -> master, origin/trunk, origin/master, origin/HEAD)
>> 2019-11-01  Kewen Lin  <[hidden email]>
>> 29f4f5f13b9 [C++ PATCH] cleanup check_field_decls
>> 0f931fb75ae 2019-11-01  Kewen Lin  <[hidden email]>
>> e9c4da22199 OpenMP] use_device_addr/use_device_ptr with Fortran
>> allocatable/pointer arrays
>> 377311a90fa 2019-11-01  Kewen Lin  <[hidden email]>
>> cc286dd8517 Daily bump.
>> 8e87e30df8d Regenerate libstdc++ HTML docs
>> fad04d507e0 Add remaining changes from P1065R2 "constexpr INVOKE"
>> d5e4b5a17de Partial implementation of C++20 of <ranges> header
>> 345d712f776 Test --help=common for full sentences
>> a737cc23c15     PR preprocessor/92296   * internal.h (struct
>> def_pragma_macro): Add is_builtin bitfield.
>> (_cpp_restore_special_builtin): Declare.        * init.c
>> (_cpp_restore_special_builtin): New function.  * directives.c
>> (do_pragma_push_macro): For NT_BUILTIN_MACRO     set is_builtin and
>> don't try to grab definition.        (cpp_pop_definition): Use
>> _cpp_restore_special_builtin to restore       builtin macros.
>> e9c843f92f6 2019-10-31  Jozef Lawrynowicz  <[hidden email]>
>> d7069e154ee [AArch64] Fix g++.target/aarch64/sve/vcond_1_run.C
>> ae5f034c085 [AArch64] Split gcc.target/aarch64/sve/vcond_4*
>>
>> As you can see, some of these are useful and give a good summary of the
>> patch, others only tell me who committed the patch, which is less than
>> useful.  In other cases almost the entire ChangeLog entry gets printed
>> because there is no blank line to tell git where the end of the summary
>> lies.
>>
>> The normal convention in git is that the one line summary is essentially
>> the subject line of the email message that describes the patch and is
>> then followed by a blank line before the body of the commit message.
>
> I've already proposed a more specific format for libstdc++:
> https://gcc.gnu.org/ml/libstdc++/2019-09/msg00122.html
>

Well having additional requirements for a component on top of 'global'
requirements doesn't pose a real problem as long as the maintainers of
that component concur.

Having incompatible requirements would be problematic, though.

R.
Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Segher Boessenkool
In reply to this post by Jonathan Wakely-4
On Mon, Nov 04, 2019 at 04:19:25PM +0000, Jonathan Wakely wrote:
> I've already proposed a more specific format for libstdc++:
> https://gcc.gnu.org/ml/libstdc++/2019-09/msg00122.html

PR libstdc++/12345 takes up the first 19 chars of the short subject,
adding no useful information (unless the reader knows all PRs by heart,
you need to look it up to know what it is).

I usually put (PR12345) at the end of the subject.  The area is clear
from the rest of the subject already.


Segher
Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Joseph Myers
On Mon, 4 Nov 2019, Segher Boessenkool wrote:

> On Mon, Nov 04, 2019 at 04:19:25PM +0000, Jonathan Wakely wrote:
> > I've already proposed a more specific format for libstdc++:
> > https://gcc.gnu.org/ml/libstdc++/2019-09/msg00122.html
>
> PR libstdc++/12345 takes up the first 19 chars of the short subject,
> adding no useful information (unless the reader knows all PRs by heart,
> you need to look it up to know what it is).
>
> I usually put (PR12345) at the end of the subject.  The area is clear
> from the rest of the subject already.

Agreed.  (Hint to patch submitters: if the subject line of your patch
submission is just "Fix PR12345" or similar, people are less likely to
review your patch because nothing about the subject tells anyone that the
patch is in their area and so something they should pay attention to.  
Patch submissions need to have subjects that make clear very quickly what
the patch is about.  This is also why I don't care for [PATCH] tags at the
start of subject lines - they take away space for saying what the patch is
about, and on gcc-patches we can expect things are patches, [PATCH]
doesn't add useful information.)

I've been using git-style commit messages in GCC for the past five years.

--
Joseph S. Myers
[hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Segher Boessenkool
In reply to this post by Martin Jambor-3
On Mon, Nov 04, 2019 at 01:43:17PM +0100, Martin Jambor wrote:

> On Mon, Nov 04 2019, Richard Earnshaw (lists) wrote:
> > Some tools, particularly gitk or git log --oneline, can use one-line
> > summaries from a commit's log message when listing commits.  It would be
> > nice if we could start adopting a style that is compatible with this, so
> > that in future commits are summarized in a useful way.
>
> ...
>
> > The normal convention in git is that the one line summary is essentially
> > the subject line of the email message that describes the patch and is
> > then followed by a blank line before the body of the commit message.
> >
>
> I wholeheartedly agree.  Thanks to everyone already doing this and
> everyone else, please just start, adding a summary line takes just
> minimal effort.

Making a good subject is work and takes time, just like making a good
commit message, just like making a good patch.

The effort is worth it for at least two reasons:

1) More people read the commit message than write it, and this balance
shifts much further towards "read" if you consider the commit history
instead of just the patch submissions.

2) Being forced to describe your patches often makes you find problems
with them, or more generally, can make you actually understand what you
are doing ;-)


Segher
Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Segher Boessenkool
In reply to this post by Joseph Myers
On Mon, Nov 04, 2019 at 05:42:47PM +0000, Joseph Myers wrote:
> This is also why I don't care for [PATCH] tags at the
> start of subject lines - they take away space for saying what the patch is
> about, and on gcc-patches we can expect things are patches, [PATCH]
> doesn't add useful information.)

Yeah, but various tools automatically add them (and v2 and 1/4 etc. tags,
which are extremely useful), so it would be very inconvenient to outlaw
them.  Oh, and it is what all of the rest of the world uses, I don't even
consciously *see* the standard stuff anymore, it's only when people get
creative ;-)


Segher
Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Kewen.Lin-2
In reply to this post by Richard Earnshaw (lists)
Hi,

on 2019/11/4 下午6:29, Richard Earnshaw (lists) wrote:

> With the move to git fairly imminent now it would be nice if we could agree on a more git-friendly style of commit messages; and, ideally, start using them now so that the converted repository can benefit from this.
>
> Some tools, particularly gitk or git log --oneline, can use one-line summaries from a commit's log message when listing commits.  It would be nice if we could start adopting a style that is compatible with this, so that in future commits are summarized in a useful way.  Unfortunately, some of our existing commits show no useful information with tools like this.
>
> Eg.
>
> git log --oneline
> 2b70dbd64b5 (HEAD -> master, origin/trunk, origin/master, origin/HEAD) 2019-11-01  Kewen Lin  <[hidden email]>
> 29f4f5f13b9 [C++ PATCH] cleanup check_field_decls
> 0f931fb75ae 2019-11-01  Kewen Lin  <[hidden email]>
> e9c4da22199 OpenMP] use_device_addr/use_device_ptr with Fortran allocatable/pointer arrays
> 377311a90fa 2019-11-01  Kewen Lin  <[hidden email]>

Sorry for the awful commit messages and thanks a lot for raising this up to stop me from stumbling continuously.

I just updated all my svn commit comments by "svn propedit svn:log --revprop -r N --editor-cmd vim",
but I guess it won't help any more if the upcoming git repo will come from some existing mirror?


BR,
Kewen

Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Jonathan Wakely-4
In reply to this post by Joseph Myers
On Mon, 4 Nov 2019 at 17:42, Joseph Myers wrote:

>
> On Mon, 4 Nov 2019, Segher Boessenkool wrote:
>
> > On Mon, Nov 04, 2019 at 04:19:25PM +0000, Jonathan Wakely wrote:
> > > I've already proposed a more specific format for libstdc++:
> > > https://gcc.gnu.org/ml/libstdc++/2019-09/msg00122.html
> >
> > PR libstdc++/12345 takes up the first 19 chars of the short subject,
> > adding no useful information (unless the reader knows all PRs by heart,
> > you need to look it up to know what it is).
> >
> > I usually put (PR12345) at the end of the subject.  The area is clear
> > from the rest of the subject already.
>
> Agreed.  (Hint to patch submitters: if the subject line of your patch
> submission is just "Fix PR12345" or similar, people are less likely to
> review your patch because nothing about the subject tells anyone that the
> patch is in their area and so something they should pay attention to.
> Patch submissions need to have subjects that make clear very quickly what
> the patch is about.  This is also why I don't care for [PATCH] tags at the
> start of subject lines - they take away space for saying what the patch is
> about, and on gcc-patches we can expect things are patches, [PATCH]
> doesn't add useful information.)

I don't mind [PATCH] in the subject of patch emails (maybe because
nearly all my patches go to libstdc++@ as well, and not all mails on
that list are patches), but it has negative value in the commit log.

My mail to the libstdc++ list should have noted that [PATCH] tags in
the email subject should be omitted from the summary in the first line
of the commit log.


> I've been using git-style commit messages in GCC for the past five years.

I think I only started four years ago :-)
Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Jason Merrill
On Tue, Nov 5, 2019 at 11:07 AM Jonathan Wakely <[hidden email]> wrote:

> On Mon, 4 Nov 2019 at 17:42, Joseph Myers wrote:
> > On Mon, 4 Nov 2019, Segher Boessenkool wrote:
> >
> > > On Mon, Nov 04, 2019 at 04:19:25PM +0000, Jonathan Wakely wrote:
> > > > I've already proposed a more specific format for libstdc++:
> > > > https://gcc.gnu.org/ml/libstdc++/2019-09/msg00122.html
> > >
> > > PR libstdc++/12345 takes up the first 19 chars of the short subject,
> > > adding no useful information (unless the reader knows all PRs by heart,
> > > you need to look it up to know what it is).
> > >
> > > I usually put (PR12345) at the end of the subject.  The area is clear
> > > from the rest of the subject already.
> >
> > Agreed.  (Hint to patch submitters: if the subject line of your patch
> > submission is just "Fix PR12345" or similar, people are less likely to
> > review your patch because nothing about the subject tells anyone that the
> > patch is in their area and so something they should pay attention to.
> > Patch submissions need to have subjects that make clear very quickly what
> > the patch is about.  This is also why I don't care for [PATCH] tags at the
> > start of subject lines - they take away space for saying what the patch is
> > about, and on gcc-patches we can expect things are patches, [PATCH]
> > doesn't add useful information.)
>
> I don't mind [PATCH] in the subject of patch emails (maybe because
> nearly all my patches go to libstdc++@ as well, and not all mails on
> that list are patches), but it has negative value in the commit log.

I actively like [PATCH] in the subject line because I see patch mail
interleaved with other mail in my inbox.

> My mail to the libstdc++ list should have noted that [PATCH] tags in
> the email subject should be omitted from the summary in the first line
> of the commit log.

And git format-patch/git am automatically add and remove [PATCH] appropriately.

I tend to put the PR number at the beginning of the line, but I don't
object to putting it at the end instead.

Jason

Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Marek Polacek-3
On Tue, Nov 05, 2019 at 11:27:50AM +0000, Jason Merrill wrote:

> On Tue, Nov 5, 2019 at 11:07 AM Jonathan Wakely <[hidden email]> wrote:
> > On Mon, 4 Nov 2019 at 17:42, Joseph Myers wrote:
> > > On Mon, 4 Nov 2019, Segher Boessenkool wrote:
> > >
> > > > On Mon, Nov 04, 2019 at 04:19:25PM +0000, Jonathan Wakely wrote:
> > > > > I've already proposed a more specific format for libstdc++:
> > > > > https://gcc.gnu.org/ml/libstdc++/2019-09/msg00122.html
> > > >
> > > > PR libstdc++/12345 takes up the first 19 chars of the short subject,
> > > > adding no useful information (unless the reader knows all PRs by heart,
> > > > you need to look it up to know what it is).
> > > >
> > > > I usually put (PR12345) at the end of the subject.  The area is clear
> > > > from the rest of the subject already.
> > >
> > > Agreed.  (Hint to patch submitters: if the subject line of your patch
> > > submission is just "Fix PR12345" or similar, people are less likely to
> > > review your patch because nothing about the subject tells anyone that the
> > > patch is in their area and so something they should pay attention to.
> > > Patch submissions need to have subjects that make clear very quickly what
> > > the patch is about.  This is also why I don't care for [PATCH] tags at the
> > > start of subject lines - they take away space for saying what the patch is
> > > about, and on gcc-patches we can expect things are patches, [PATCH]
> > > doesn't add useful information.)
> >
> > I don't mind [PATCH] in the subject of patch emails (maybe because
> > nearly all my patches go to libstdc++@ as well, and not all mails on
> > that list are patches), but it has negative value in the commit log.
>
> I actively like [PATCH] in the subject line because I see patch mail
> interleaved with other mail in my inbox.
>
> > My mail to the libstdc++ list should have noted that [PATCH] tags in
> > the email subject should be omitted from the summary in the first line
> > of the commit log.
>
> And git format-patch/git am automatically add and remove [PATCH] appropriately.

Wrt [PATCH]: if we keep it, do we want to have a system to distinguish
C/C++/... patches?  Do we want [C++ PATCH] or [PATCH][C++] or [C++][PATCH],
something else?  (I find the latter two a bit ugly.)

Marek

Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

David Malcolm
In reply to this post by Jason Merrill
On Tue, 2019-11-05 at 11:27 +0000, Jason Merrill wrote:

> On Tue, Nov 5, 2019 at 11:07 AM Jonathan Wakely <
> [hidden email]> wrote:
> > On Mon, 4 Nov 2019 at 17:42, Joseph Myers wrote:
> > > On Mon, 4 Nov 2019, Segher Boessenkool wrote:
> > >
> > > > On Mon, Nov 04, 2019 at 04:19:25PM +0000, Jonathan Wakely
> > > > wrote:
> > > > > I've already proposed a more specific format for libstdc++:
> > > > > https://gcc.gnu.org/ml/libstdc++/2019-09/msg00122.html
> > > >
> > > > PR libstdc++/12345 takes up the first 19 chars of the short
> > > > subject,
> > > > adding no useful information (unless the reader knows all PRs
> > > > by heart,
> > > > you need to look it up to know what it is).
> > > >
> > > > I usually put (PR12345) at the end of the subject.  The area is
> > > > clear
> > > > from the rest of the subject already.
> > >
> > > Agreed.  (Hint to patch submitters: if the subject line of your
> > > patch
> > > submission is just "Fix PR12345" or similar, people are less
> > > likely to
> > > review your patch because nothing about the subject tells anyone
> > > that the
> > > patch is in their area and so something they should pay attention
> > > to.
> > > Patch submissions need to have subjects that make clear very
> > > quickly what
> > > the patch is about.  This is also why I don't care for [PATCH]
> > > tags at the
> > > start of subject lines - they take away space for saying what the
> > > patch is
> > > about, and on gcc-patches we can expect things are patches,
> > > [PATCH]
> > > doesn't add useful information.)
> >
> > I don't mind [PATCH] in the subject of patch emails (maybe because
> > nearly all my patches go to libstdc++@ as well, and not all mails
> > on
> > that list are patches), but it has negative value in the commit
> > log.
>
> I actively like [PATCH] in the subject line because I see patch mail
> interleaved with other mail in my inbox.

FWIW my convention has been to put "[PATCH]" in the email subject line
for patches I want reviewed, and "[committed]" for patches that I've
already self-approved (or are obvious) and thus don't need review.

+1 from me on making commit messages have git-friendly summary lines
(I've been doing this myself since shortly after I joined gcc).

I'm not too bothered about the precise format FWIW - maybe it's better
not to be too prescriptive about the format, beyond "make them concise,
and useful for you and your fellow maintainers"?   I try to use the
same message as the email subject line, to make cross-referencing
between the mailing list and source repos easier when doing
"archaeology".

(that said, keeping "[PATCH]" in the *commit* message is a pet peeve of
mine, as it's redundant).

I also tend to put in the "blurb" from the email into the commit
message, especially if it's a pertinent high-level description of the
purpose of the *change* (as opposed to a description of the *code*,
which should live in a comment in the code, rather than the metadata).

> > My mail to the libstdc++ list should have noted that [PATCH] tags
> > in
> > the email subject should be omitted from the summary in the first
> > line
> > of the commit log.
>
> And git format-patch/git am automatically add and remove [PATCH]
> appropriately.
>
> I tend to put the PR number at the beginning of the line, but I don't
> object to putting it at the end instead.
>
> Jason
>

Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Richard Earnshaw (lists)
In reply to this post by Jeff Law
On 04/11/2019 16:04, Jeff Law wrote:

> On 11/4/19 3:29 AM, Richard Earnshaw (lists) wrote:
>> With the move to git fairly imminent now it would be nice if we could
>> agree on a more git-friendly style of commit messages; and, ideally,
>> start using them now so that the converted repository can benefit from
>> this.
>
> I'd suggest we sync policy with glibc.  They're further along on the
> ChangeLog issues.  Whatever they do in this space we should follow --
> aren't we going to be using some of their hooks/scripts?
>
> jeff
>

OK, based on these discussions here's an initial proposal for some
wording in contribute.html for the web site.  I've based it strongly on
the libc version, mostly with some restructuring and a tweak around bug
numbers.

R.

emails.patch (5K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Segher Boessenkool
In reply to this post by Jonathan Wakely-4
On Tue, Nov 05, 2019 at 11:07:05AM +0000, Jonathan Wakely wrote:
> On Mon, 4 Nov 2019 at 17:42, Joseph Myers wrote:
> > I've been using git-style commit messages in GCC for the past five years.
>
> I think I only started four years ago :-)

I am        r210190   Wed May 7 22:00:58 2014 +0000
Joseph is   r214526   Tue Aug 26 17:06:31 2014 +0000
You are     r218698   Sat Dec 13 20:44:06 2014 +0000

Anyone else playing?  ;-)


Segher
Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Iain Sandoe
Segher Boessenkool <[hidden email]> wrote:

> On Tue, Nov 05, 2019 at 11:07:05AM +0000, Jonathan Wakely wrote:
>> On Mon, 4 Nov 2019 at 17:42, Joseph Myers wrote:
>>> I've been using git-style commit messages in GCC for the past five years.
>>
>> I think I only started four years ago :-)
>
> I am        r210190   Wed May 7 22:00:58 2014 +0000
> Joseph is   r214526   Tue Aug 26 17:06:31 2014 +0000
> You are     r218698   Sat Dec 13 20:44:06 2014 +0000
>
> Anyone else playing?  ;-)

I am - but probably for much less time than the others …

I think I started around the time Joseph observed it would be
a good idea to make the eventual commit messages nicer.

Iain

>
>
> Segher


Reply | Threaded
Open this post in threaded view
|

Re: Commit messages and the move to git

Richard Earnshaw (lists)
In reply to this post by Marek Polacek-3
On 05/11/2019 14:12, Marek Polacek wrote:

> On Tue, Nov 05, 2019 at 11:27:50AM +0000, Jason Merrill wrote:
>> On Tue, Nov 5, 2019 at 11:07 AM Jonathan Wakely <[hidden email]> wrote:
>>> On Mon, 4 Nov 2019 at 17:42, Joseph Myers wrote:
>>>> On Mon, 4 Nov 2019, Segher Boessenkool wrote:
>>>>
>>>>> On Mon, Nov 04, 2019 at 04:19:25PM +0000, Jonathan Wakely wrote:
>>>>>> I've already proposed a more specific format for libstdc++:
>>>>>> https://gcc.gnu.org/ml/libstdc++/2019-09/msg00122.html
>>>>>
>>>>> PR libstdc++/12345 takes up the first 19 chars of the short subject,
>>>>> adding no useful information (unless the reader knows all PRs by heart,
>>>>> you need to look it up to know what it is).
>>>>>
>>>>> I usually put (PR12345) at the end of the subject.  The area is clear
>>>>> from the rest of the subject already.
>>>>
>>>> Agreed.  (Hint to patch submitters: if the subject line of your patch
>>>> submission is just "Fix PR12345" or similar, people are less likely to
>>>> review your patch because nothing about the subject tells anyone that the
>>>> patch is in their area and so something they should pay attention to.
>>>> Patch submissions need to have subjects that make clear very quickly what
>>>> the patch is about.  This is also why I don't care for [PATCH] tags at the
>>>> start of subject lines - they take away space for saying what the patch is
>>>> about, and on gcc-patches we can expect things are patches, [PATCH]
>>>> doesn't add useful information.)
>>>
>>> I don't mind [PATCH] in the subject of patch emails (maybe because
>>> nearly all my patches go to libstdc++@ as well, and not all mails on
>>> that list are patches), but it has negative value in the commit log.
>>
>> I actively like [PATCH] in the subject line because I see patch mail
>> interleaved with other mail in my inbox.
>>
>>> My mail to the libstdc++ list should have noted that [PATCH] tags in
>>> the email subject should be omitted from the summary in the first line
>>> of the commit log.
>>
>> And git format-patch/git am automatically add and remove [PATCH] appropriately.
>
> Wrt [PATCH]: if we keep it, do we want to have a system to distinguish
> C/C++/... patches?  Do we want [C++ PATCH] or [PATCH][C++] or [C++][PATCH],
> something else?  (I find the latter two a bit ugly.)
>

"git am --keep-non-patch" will strip sequences containing [.*PATCH.*]
(not a strict regexp, .* is anything other than ']'), and keep other
[.*] annotations.  I don't know if this applies only up to the first
non-matching sequence, or at any point.  See git-mailinfo's -b flag.
But my proposal (see post earlier) is that we should use <component>: in
the same way that libc (and, I understand, linux kernel folk) do.

R.

> Marek
>

1234 ... 6