Template for commit messages

On Thu, Jan 28, 2016 at 03:52:00AM -0500, Bruce Momjian wrote:

There has been a request in the FOSDEM developers meeting that
committers use a more consistent format for commit messages. This is
the format I use:

Here is an updated version that includes a potential bug number:

-- email subject limit -----------------------------------------
-- gitweb summary limit --------------------------

Report by

Bug #

Patch by

Reviewed by

Backpatch through

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I. As I am, so you will be. +
+ Roman grave inscription                             +

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Hi,

On 01/28/2016 11:06 AM, Bruce Momjian wrote:

On Thu, Jan 28, 2016 at 03:52:00AM -0500, Bruce Momjian wrote:

There has been a request in the FOSDEM developers meeting that
committers use a more consistent format for commit messages. This is
the format I use:

Here is an updated version that includes a potential bug number:

-- email subject limit -----------------------------------------
-- gitweb summary limit --------------------------

Report by

Bug #

Patch by

Reviewed by

Backpatch through

Any reason why not to adapt the git message conventions from kernel?

https://git.wiki.kernel.org/index.php/CommitMessageConventions

I'd expect there are tools already working with that format, making the
life easier for us.

regards

--
Tomas Vondra http://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Thu, Jan 28, 2016 at 11:30:58AM +0100, Tomas Vondra wrote:

Any reason why not to adapt the git message conventions from kernel?

https://git.wiki.kernel.org/index.php/CommitMessageConventions

I'd expect there are tools already working with that format, making
the life easier for us.

Good idea. :-) Updated template:

-- email subject limit -----------------------------------------
-- gitweb summary limit --------------------------

Reported-by:

Bug:

Patch-by:

Reviewed-by:

Backpatch through:

I had to make up "Patch-by:" as it wasn't listed.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I. As I am, so you will be. +
+ Roman grave inscription                             +

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Thu, Jan 28, 2016 at 11:49 AM, Bruce Momjian <bruce@momjian.us> wrote:

On Thu, Jan 28, 2016 at 11:30:58AM +0100, Tomas Vondra wrote:

Any reason why not to adapt the git message conventions from kernel?

https://git.wiki.kernel.org/index.php/CommitMessageConventions

I'd expect there are tools already working with that format, making
the life easier for us.

Good idea. :-) Updated template:

-- email subject limit -----------------------------------------
-- gitweb summary limit --------------------------

Reported-by:

Bug:

Patch-by:

Reviewed-by:

Backpatch through:

I had to make up "Patch-by:" as it wasn't listed.

The original format uses the author for that (author != committer in git),
but that changes how we work a bit more. I'd be happy to just clal it
"Author" rather than "Patch-by".

I also suggest a - in "Backpatch-through:" -- since all the others are
intentionally mad ewithout a space, I assume that's for easier parsing.

They also had tested-by, it might be an idea to include that as well?

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

Bruce Momjian wrote:

There has been a request in the FOSDEM developers meeting that
committers use a more consistent format for commit messages.

Let me point out that the reason this is being put forward is to make
sure we have the reviewers listed for each patch, so that we can add a
paragraph somewhere at the bottom of the release notes listing people
that helped with the release.

--
�lvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Magnus Hagander wrote:

They also had tested-by, it might be an idea to include that as well?

How about
User-Interface-Bikeshedded-By:
?

--
�lvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Thu, Jan 28, 2016 at 11:53:44AM +0100, Magnus Hagander wrote:

The original format uses the author for that (author != committer in git), but
that changes how we work a bit more. I'd be happy to just clal it "Author"
rather than "Patch-by".

I also suggest a - in "Backpatch-through:" -- since all the others are
intentionally mad ewithout a space, I assume that's for easier parsing.

They also had tested-by, it might be an idea to include that as well?�

OK, updated based on those suggestions:

-- email subject limit -----------------------------------------
-- gitweb summary limit --------------------------

Reported-by:

Bug:

Author:

Reviewed-by:

Tested-by:

Backpatch-through:

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I. As I am, so you will be. +
+ Roman grave inscription                             +

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Dne 28. 1. 2016 11:57 napsal uživatel "Alvaro Herrera" <
alvherre@2ndquadrant.com>:

Magnus Hagander wrote:

They also had tested-by, it might be an idea to include that as well?

How about
User-Interface-Bikeshedded-By:
?

+1

On Thu, Jan 28, 2016 at 3:52 AM, Bruce Momjian <bruce@momjian.us> wrote:

There has been a request in the FOSDEM developers meeting that
committers use a more consistent format for commit messages. This is
the format I use:

-- email subject limit -----------------------------------------
-- gitweb summary limit --------------------------

Report by

Patch by

Reviewed by

Backpatch through

The dashed lines are used to specify a target length for the summary
line and are automatically removed before the commit message is posted.

One of the things I like about the current free-form approach is that
you can indicate nuances, like:

Person X reviewed an earlier version of this patch that was a lot
different than this one.
Person X reviewed this patch but didn't totally endorse it.
Person X wrote the documentation for the patch, but none of the code.
Person X wrote the vast bulk of this patch, even though there are some
other authors.

Should I just abandon the idea of trying to capture those details, or
does this format contemplate a way to include them?

(Also an important question: Has Tom agreed to use this new format?
Because I think that anything the rest of agree on that he's not
prepared to endorse is not going to have much value.)

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 01/28/2016 01:57 PM, Robert Haas wrote:
...

One of the things I like about the current free-form approach is that
you can indicate nuances, like:

Person X reviewed an earlier version of this patch that was a lot
different than this one.
Person X reviewed this patch but didn't totally endorse it.
Person X wrote the documentation for the patch, but none of the code.
Person X wrote the vast bulk of this patch, even though there are some
other authors.

Should I just abandon the idea of trying to capture those details, or
does this format contemplate a way to include them?

Why can't we do both? That is, have a free-form text with the nuances,
and then Reviewed-By listing the main reviewers? The first one is for
humans, the other one for automated tools.

(Also an important question: Has Tom agreed to use this new format?
Because I think that anything the rest of agree on that he's not
prepared to endorse is not going to have much value.)

I can't speak for Tom, but I'm sitting fairly close to him and I haven't
heard any complains or even groaning.

regards

--
Tomas Vondra http://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Thu, Jan 28, 2016 at 8:04 AM, Tomas Vondra
<tomas.vondra@2ndquadrant.com> wrote:

On 01/28/2016 01:57 PM, Robert Haas wrote:

One of the things I like about the current free-form approach is that
you can indicate nuances, like:

Person X reviewed an earlier version of this patch that was a lot
different than this one.
Person X reviewed this patch but didn't totally endorse it.
Person X wrote the documentation for the patch, but none of the code.
Person X wrote the vast bulk of this patch, even though there are some
other authors.

Should I just abandon the idea of trying to capture those details, or
does this format contemplate a way to include them?

Why can't we do both? That is, have a free-form text with the nuances, and
then Reviewed-By listing the main reviewers? The first one is for humans,
the other one for automated tools.

I'm not objecting to or endorsing any specific proposal, just asking
what we want to do about this. I think the trick if we do it that way
will be to avoid having it seem like too much duplication, but there
may be a way to manage that.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Thu, Jan 28, 2016 at 6:16 AM, Tomas Vondra
<tomas.vondra@2ndquadrant.com> wrote:

How about
User-Interface-Bikeshedded-By:
?

+1

That's sort of implicitly pejorative. Maybe we could find another
way to phrase that, like "Design-suggestions-by" or maybe a more
general "Suggestions-by".

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Thu, Jan 28, 2016 at 09:31:46AM -0500, Robert Haas wrote:

On Thu, Jan 28, 2016 at 6:16 AM, Tomas Vondra
<tomas.vondra@2ndquadrant.com> wrote:

How about
User-Interface-Bikeshedded-By:
?

+1

That's sort of implicitly pejorative. Maybe we could find another
way to phrase that, like "Design-suggestions-by" or maybe a more
general "Suggestions-by".

I wasn't sure if "User-Interface-Bikeshedded-By" related to the patch,
or to the discussion of labels for the commit messages.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I. As I am, so you will be. +
+ Roman grave inscription                             +

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Thu, Jan 28, 2016 at 9:34 AM, Bruce Momjian <bruce@momjian.us> wrote:

On Thu, Jan 28, 2016 at 09:31:46AM -0500, Robert Haas wrote:

On Thu, Jan 28, 2016 at 6:16 AM, Tomas Vondra
<tomas.vondra@2ndquadrant.com> wrote:

How about
User-Interface-Bikeshedded-By:
?

+1

That's sort of implicitly pejorative. Maybe we could find another
way to phrase that, like "Design-suggestions-by" or maybe a more
general "Suggestions-by".

I wasn't sure if "User-Interface-Bikeshedded-By" related to the patch,
or to the discussion of labels for the commit messages.

I thought it was a proposed commit message label and that the original
suggestion was tongue-in-cheek, but I might be misreading things.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Robert Haas <robertmhaas@gmail.com> writes:

On Thu, Jan 28, 2016 at 8:04 AM, Tomas Vondra
<tomas.vondra@2ndquadrant.com> wrote:

Why can't we do both? That is, have a free-form text with the nuances, and
then Reviewed-By listing the main reviewers? The first one is for humans,
the other one for automated tools.

I'm not objecting to or endorsing any specific proposal, just asking
what we want to do about this. I think the trick if we do it that way
will be to avoid having it seem like too much duplication, but there
may be a way to manage that.

FWIW, I'm a bit suspicious of the idea that we need to make the commit
messages automated-tool-friendly. What tools are there that would need
to extract this info, and would we trust them if they didn't understand
"nuances"?

I'm on board with Bruce's template as being a checklist of points to be
sure to cover when composing a commit message. I'm not sure we need
fixed-format rules.

regards, tom lane

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Robert Haas wrote:

On Thu, Jan 28, 2016 at 6:16 AM, Tomas Vondra
<tomas.vondra@2ndquadrant.com> wrote:

How about
User-Interface-Bikeshedded-By:
?

+1

That's sort of implicitly pejorative. Maybe we could find another
way to phrase that, like "Design-suggestions-by" or maybe a more
general "Suggestions-by".

Apologies, I was kidding actually -- I don't think we should list people
on patches just because they provided some input in the thread, but
people that actually reviewed the patch. Otherwise we risk diluting the
list in the release notes (or wherever it is that we end up crediting
reviewers/contributors), which is also undesirable.

--
�lvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Thu, Jan 28, 2016 at 9:52 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Robert Haas <robertmhaas@gmail.com> writes:

On Thu, Jan 28, 2016 at 8:04 AM, Tomas Vondra
<tomas.vondra@2ndquadrant.com> wrote:

Why can't we do both? That is, have a free-form text with the nuances, and
then Reviewed-By listing the main reviewers? The first one is for humans,
the other one for automated tools.

I'm not objecting to or endorsing any specific proposal, just asking
what we want to do about this. I think the trick if we do it that way
will be to avoid having it seem like too much duplication, but there
may be a way to manage that.

FWIW, I'm a bit suspicious of the idea that we need to make the commit
messages automated-tool-friendly. What tools are there that would need
to extract this info, and would we trust them if they didn't understand
"nuances"?

I'm on board with Bruce's template as being a checklist of points to be
sure to cover when composing a commit message. I'm not sure we need
fixed-format rules.

Well, I think what people are asking for is precisely a fixed format,
and I do think there is value in that. It's nice to capture the
nuance, but the nuance is going to get flattened out anyway when the
release notes are created. If we all agree to use a fixed format,
then a bunch of work there that probably has to be done manually can
be automated. However, if we all agree to use a fixed format except
for you, we might as well just forget the whole thing, because the
percentage of commits that are done by you is quite high.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On Thu, Jan 28, 2016 at 03:52:25PM +0100, Tom Lane wrote:

Robert Haas <robertmhaas@gmail.com> writes:

On Thu, Jan 28, 2016 at 8:04 AM, Tomas Vondra
<tomas.vondra@2ndquadrant.com> wrote:

Why can't we do both? That is, have a free-form text with the nuances, and
then Reviewed-By listing the main reviewers? The first one is for humans,
the other one for automated tools.

I'm not objecting to or endorsing any specific proposal, just asking
what we want to do about this. I think the trick if we do it that way
will be to avoid having it seem like too much duplication, but there
may be a way to manage that.

FWIW, I'm a bit suspicious of the idea that we need to make the commit
messages automated-tool-friendly. What tools are there that would need
to extract this info, and would we trust them if they didn't understand
"nuances"?

I'm on board with Bruce's template as being a checklist of points to be
sure to cover when composing a commit message. I'm not sure we need
fixed-format rules.

I've been asking for them for years so I can spend my time on the
PostgreSQL Weekly News more efficiently. Maybe it's more efficient
for me to do this arranging than for each committer to do it. I'd
like to imagine that committers are in a better position than I to
summarize their work.

Whatever we decide on here, I'd really appreciate it if every patch
sent to the list came with a sentence describing what that version of
it does, as scope drift frequently makes Subject: lines completely
wrong.

While I'm at it, I'd like to thank Andres Freund, Peter Geoghegan, and
Robert Haas in particular for making a habit of writing detailed
summaries and splitting patches into logical chunks. All errors in
the PostgreSQL Weekly News are mine, but a little organization like
theirs would go a very long way, and not just for me.

Cheers,
David.
--
David Fetter <david@fetter.org> http://fetter.org/
Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter
Skype: davidfetter XMPP: david.fetter@gmail.com

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 01/28/2016 06:57 AM, Robert Haas wrote:

I'm on board with Bruce's template as being a checklist of points to be
sure to cover when composing a commit message. I'm not sure we need
fixed-format rules.

Well, I think what people are asking for is precisely a fixed format,
and I do think there is value in that. It's nice to capture the
nuance, but the nuance is going to get flattened out anyway when the
release notes are created. If we all agree to use a fixed format,
then a bunch of work there that probably has to be done manually can
be automated. However, if we all agree to use a fixed format except
for you, we might as well just forget the whole thing, because the
percentage of commits that are done by you is quite high.

Yes, we are either all in or we may as well forgo this.

Sincerely,

Joshua D. Drake

--
Command Prompt, Inc. http://the.postgres.company/
+1-503-667-4564
PostgreSQL Centered full stack support, consulting and development.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers