This is the mail archive of the mailing list for the GCC project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Commit messages and the move to git


On Tue, Nov 05, 2019 at 09:50:37AM -0500, David Malcolm wrote:
> 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.

And there is [RFC] as well.

As already noted, the advantage of [PATCH] is that many tools know how
to handle that, already, so it may fit into your workflow better (git am
removes *all* leading bracketed strings, by default).

Also making a mail that can just be applied with git-am is useful if you
want other people to be able to commit your patches.  We usually commit
our own patches, but this is still important for people who want to test
out a patch, etc.

I recommend preparing your patches with git format-patch: it takes care
of all details for you.  You still should follow some rules, like using
scissors lines, and maximum line length 72, etc., but it makes mails
that follow all our rules for mime encoding and the like.

> 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"?


If we want to standardise on other things, like have subjects like for
example "combine: Frob the fubar" (and what those tags should be exactly)
that will work itself out hopefully.  As long as subjects are nice and
useful, everyone should be happy.

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

I use the whole email as commit message.  This works quite well imo, and
it's the "standard" way of using git.  This also works nicely with
patchwork, if anyone but me uses that still :-)

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

Purpose and mechanics and whatnot, yeah -- but of the change, indeed: it
should be text relevant to people who want to know what changed (and why).
Anything you would put in the mail thread that people looking at the
committed patches would still like to see.

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

I don't think we need to standardise this, certainly not before we have
enough experience with this.  Everyone works differently, we should just
figure out a way we can work together best.  A PR # at the start of the
subject can be useful, if it leaves enough space for other important info.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]