Re: Deriving release notes from git commit messages

There's been a steady flow of messages on pgsql-advocacy since last
month (threads "Crediting sponsors in release notes?" and "Crediting
reviewers & bug-reporters in the release notes") talking about who/how
should receive credited for their work on PostgreSQL. That discussion
seems to be me heading in one inevitable direction: it's not going to
be possible to make everyone happy unless there's a way to track all of
these things for each feature added to PostgreSQL:

-Short description for the release notes
-Feature author(s)
-Reviewers and bug reporters
-Sponsors
-Main git commit adding the feature

Now, this is clearly the job for a tool, because the idea that any
person capable of doing this work will actually do it is
laughable--everyone qualified is too busy. It strikes me however that
the current production of the release notes is itself a time consuming
and error-prone process that could also be improved by automation. I
had an idea for pushing forward both these at once.

Committers here are pretty good at writing terse but clear summaries of
new features when they are added. These are generally distilled further
for the release notes. It strikes me that a little decoration of commit
messages might go a long way toward saving time in a few areas here.
I'll pick a simple easy example I did to demonstrate; I wrote a small
optimization to commit_delay committed at
http://archives.postgresql.org/message-id/E1PQP72-0001uS-0d@gemulon.postgresql.org

This made its way into the release notes like this:

Improve performance of commit_siblings (Greg Smith)
This allows the use of commit_siblings with less overhead.

What if the commit message had been decorated like this?

Feature: Improve performance of commit_siblings

Optimize commit_siblings in two ways to improve group commit.
First, avoid scanning the whole ProcArray once we know there...

With that simple addition, two things become possible:

-Generating a first draft of the release notes for a new version could
turn into a script that parses the git commit logs, which has gotta save
somebody a whole lot of time each release that goes into the first draft
of the release notes.
-All of these other ways to analyze of the contributors would be much
easier to maintain. A little "Author:" decoration to that section of
each commit would probably be welcome too.

I'm sure someone is going to reply to this suggesting some git metadata
is the right way to handle this, but that seems like overkill to me. I
think there's enough committer time gained in faster release note
generation for this decoration to payback its overhead, which is
important to me--I'd want a change here to net close to zero for
committers. And the fact that it would also allow deriving all this
other data makes it easier to drive the goals rising out of advocacy
forward too.

--
Greg Smith 2ndQuadrant US greg(at)2ndQuadrant(dot)com Baltimore, MD
PostgreSQL Training, Services, and 24x7 Support www.2ndQuadrant.us

On Fri, Jun 24, 2011 at 5:15 PM, Greg Smith <greg(at)2ndquadrant(dot)com> wrote:
> -All of these other ways to analyze of the contributors would be much easier
> to maintain.  A little "Author:" decoration to that section of each commit
> would probably be welcome too.

I think you're quite right, that "mining" the commit logs for these
sorts of information is very much the right answer.

Initially, the choice has been to not use the Author tag in Git; I
think that came as part of the overall intent that, at least, in the
beginning, the workflow of the PostgreSQL project shouldn't diverge
terribly much from how it had been with CVS.

It makes sense to have some debate about additional features to
consider using to capture useful workflow. Sadly, I think that would
have been a very useful debate to have held at the Devs meeting in
Ottawa, when a lot of the relevant people were in a single room; it's
a bit harder now.

In any case, having some tooling to rummage through commits to
generate proposals for release notes seems like a fine idea. Even
without policy changes (e.g. - to start using Author:, and possibly
other explicit metadata), it would surely be possible to propose
release note contents that tries to use what it finds.

For instance, if the tool captured all email addresses that it finds
in a commit message, and stows them in a convenient spot, that makes
it easier for the human to review the addresses and classify which
might indicate authorship. Maybe a step ahead.
--
When confronted by a difficult problem, solve it by reducing it to the
question, "How would the Lone Ranger handle this?"

On Fri, Jun 24, 2011 at 1:15 PM, Greg Smith <greg(at)2ndquadrant(dot)com> wrote:
> There's been a steady flow of messages on pgsql-advocacy since last month
> (threads "Crediting sponsors in release notes?" and "Crediting reviewers &
> bug-reporters in the release notes") talking about who/how should receive
> credited for their work on PostgreSQL.  That discussion seems to be me
> heading in one inevitable direction:  it's not going to be possible to make
> everyone happy unless there's a way to track all of these things for each
> feature added to PostgreSQL:

I don't read -advocacy regularly, but reviewing the archives, it
doesn't seem to me that we've reached any conclusion about whether
including this information in the release notes is a good idea in the
first place. It seems to me that one name for each feature is about
at the limit of what we can reasonably do without cluttering the
release notes to the point of unreadability. I am OK with it the way
it is, but if we must change it I would argue that we ought to have
less credit there, not more. Which is not to say we shouldn't have
credit. I think crediting sponsors and reviewers and bug reporters is
a good idea. But I think the web site is the place to do that, not
the release notes.

As for annotating the commit messages, I think something like:

Reporter: Sam Jones
Author: Beverly Smith
Author: Jim Davids
Reviewer: Fred Block
Reviewer: Pauline Andrews

...would be a useful convention. I am disinclined to add a "feature"
annotation. I think it is unlikely that will end up being any more
useful than just extracting either the whole commit message or its
first line.

I am not inclined to try to track sponsors in the commit message at
all. Suppose Jeff Davis submits a patch, Stephen Frost reviews it,
and I commit it. Besides the three human beings involved,
potentially, you've got three employers who might be considered
sponsors, plus any customers of those employers who might have paid
said employer money to justify the time spent on that patch. On a big
patch, you could easily have ten companies involved in different
roles, some of whom may have made a far larger real contribution to
the development of the feature than others, and I am 100% opposed to
making it the committer's job to include all that in the commit
message. Also, unlike individuals (whose names can usually be read
off the thread in a few seconds), it is not necessarily obvious who
the corporate participants are (or which ones even WANT to be
credited). It is almost certain that the committer will sometimes get
it wrong, and the commit log is a terrible place to record information
that might need to be changed after the fact.

It seems to me that, at least for sponsorship information, it would be
far better to have a separate database that pulls in the commit logs
and then gets annotated by the people who care.

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

On 06/24/2011 01:42 PM, Robert Haas wrote:
> I am disinclined to add a "feature"
> annotation. I think it is unlikely that will end up being any more
> useful than just extracting either the whole commit message or its
> first line.
>

I don't see any good way to extract the list of commits relevant to the
release notes without something like it. Right now, you can't just mine
every commit into the release notes without getting more noise than
signal. Something that tags the ones that are adding new features or
other notable updates, as opposed to bug fixes, doc updates, etc., would
allow that separation.

> I am not inclined to try to track sponsors in the commit message at
> all.

I was not suggesting that information be part of the commit. We've
worked out a reasonable initial process for the people working on
sponsored features to record that information completely outside of the
commit or release notes data. It turns out though that process would be
easier to drive if it were easier to derive a feature->{commit,author}
list though--and that would spit out for free with the rest of this.
Improving the ability to do sponsor tracking is more of a helpful
side-effect of something that's useful for other reasons rather than a
direct goal.

--
Greg Smith 2ndQuadrant US greg(at)2ndQuadrant(dot)com Baltimore, MD
PostgreSQL Training, Services, and 24x7 Support www.2ndQuadrant.us

On Fri, Jun 24, 2011 at 2:47 PM, Greg Smith <greg(at)2ndquadrant(dot)com> wrote:
> On 06/24/2011 01:42 PM, Robert Haas wrote:
>> I am disinclined to add a "feature"
>> annotation.  I think it is unlikely that will end up being any more
>> useful than just extracting either the whole commit message or its
>> first line.
>
> I don't see any good way to extract the list of commits relevant to the
> release notes without something like it.  Right now, you can't just mine
> every commit into the release notes without getting more noise than signal.
>  Something that tags the ones that are adding new features or other notable
> updates, as opposed to bug fixes, doc updates, etc., would allow that
> separation.

Oh, I see. There's definitely some fuzziness about which commits make
it into the release notes right now and which do not - sometimes
things get missed, or sometimes Bruce omits something I would have
included or includes something I would have omitted. OTOH, it's not
clear that making every committer do that on every commit is going to
be better than having one person go through the log and decide
everything all at once.

If I were attacking this problem, I'd be inclined to make a web
application that lists all the commits in a format roughly similar to
the git API, and then lets you tag each commit with tags from some
list (feature, bug-fix, revert, repair-of-previous-commit, etc.).
Some of the tagging (e.g. docs-only) could probably even be done
automatically. Then somebody could go through once a month and update
all the tags. I'd be more more willing to volunteer to do that than I
would be to trying to get the right metadata tag in every commit...

>> I am not inclined to try to track sponsors in the commit message at
>> all.
>
> I was not suggesting that information be part of the commit.  We've worked
> out a reasonable initial process for the people working on sponsored
> features to record that information completely outside of the commit or
> release notes data.  It turns out though that process would be easier to
> drive if it were easier to derive a feature->{commit,author} list
> though--and that would spit out for free with the rest of this.  Improving
> the ability to do sponsor tracking is more of a helpful side-effect of
> something that's useful for other reasons rather than a direct goal.

OK, that makes sense.

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

On Fri, Jun 24, 2011 at 6:47 PM, Greg Smith <greg(at)2ndquadrant(dot)com> wrote:
> On 06/24/2011 01:42 PM, Robert Haas wrote:
>> I am not inclined to try to track sponsors in the commit message at
>> all.
>
> I was not suggesting that information be part of the commit.  We've worked
> out a reasonable initial process for the people working on sponsored
> features to record that information completely outside of the commit or
> release notes data.  It turns out though that process would be easier to
> drive if it were easier to derive a feature->{commit,author} list
> though--and that would spit out for free with the rest of this.  Improving
> the ability to do sponsor tracking is more of a helpful side-effect of
> something that's useful for other reasons rather than a direct goal.

In taking a peek at the documentation and comments out on the interweb
about "git amend," I don't think that it's going to be particularly
successful if we try to capture all this stuff in the commit message
and metadata, because it's tough to guarantee that *all* this data
would be correctly captured at commit time, and you can't revise it
after the commit gets pushed upstream.

That applies to anything we might want to track, whether "Author:" (at
the 'likely to be useful', and 'could quite readily get it correct the
first time' end of the spectrum) or "Sponsor:" (which is at more than
one dubious ends of spectra).

I expect that the correlation between commit and [various parties] is
something that will need to take place outside git.

The existing CommitFest data goes quite a long ways towards capturing
interesting information (with the likely exception of sponsorship);
what it's missing, at this point, is a capture of what commit or
commits wound up drawing the proposed patch into the official code
base. That suggests a pretty natural extension, and this is something
I really would like to see. I'd love to head to the CommitFest page,
and have a list of URLs pointing to the commits that implemented a
particular change.

Given that particular correspondence (e.g. - commitfest request ->
list of commits), that would help associate authors, reviewers, and
such to each commit that was related to CommitFest work. That doesn't
cover everything, but it's a plenty good start.
--
When confronted by a difficult problem, solve it by reducing it to the
question, "How would the Lone Ranger handle this?"

Robert Haas wrote:
> On Fri, Jun 24, 2011 at 2:47 PM, Greg Smith <greg(at)2ndquadrant(dot)com> wrote:
> > On 06/24/2011 01:42 PM, Robert Haas wrote:
> >> I am disinclined to add a "feature"
> >> annotation. ?I think it is unlikely that will end up being any more
> >> useful than just extracting either the whole commit message or its
> >> first line.
> >
> > I don't see any good way to extract the list of commits relevant to the
> > release notes without something like it. ?Right now, you can't just mine
> > every commit into the release notes without getting more noise than signal.
> > ?Something that tags the ones that are adding new features or other notable
> > updates, as opposed to bug fixes, doc updates, etc., would allow that
> > separation.
>
> Oh, I see. There's definitely some fuzziness about which commits make
> it into the release notes right now and which do not - sometimes
> things get missed, or sometimes Bruce omits something I would have
> included or includes something I would have omitted. OTOH, it's not
> clear that making every committer do that on every commit is going to
> be better than having one person go through the log and decide
> everything all at once.
>
> If I were attacking this problem, I'd be inclined to make a web
> application that lists all the commits in a format roughly similar to
> the git API, and then lets you tag each commit with tags from some
> list (feature, bug-fix, revert, repair-of-previous-commit, etc.).
> Some of the tagging (e.g. docs-only) could probably even be done
> automatically. Then somebody could go through once a month and update
> all the tags. I'd be more more willing to volunteer to do that than I
> would be to trying to get the right metadata tag in every commit...

That tagging is basically what I do on my first pass through the release
notes. For the gory details:

http://momjian.us/main/blogs/pgblog/2009.html#March_25_2009

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On Jun 24, 2011, at 2:28 PM, Christopher Browne wrote:
> On Fri, Jun 24, 2011 at 6:47 PM, Greg Smith <greg(at)2ndquadrant(dot)com> wrote:
>> On 06/24/2011 01:42 PM, Robert Haas wrote:
>>> I am not inclined to try to track sponsors in the commit message at
>>> all.
>>
>> I was not suggesting that information be part of the commit. We've worked
>> out a reasonable initial process for the people working on sponsored
>> features to record that information completely outside of the commit or
>> release notes data. It turns out though that process would be easier to
>> drive if it were easier to derive a feature->{commit,author} list
>> though--and that would spit out for free with the rest of this. Improving
>> the ability to do sponsor tracking is more of a helpful side-effect of
>> something that's useful for other reasons rather than a direct goal.
>
> In taking a peek at the documentation and comments out on the interweb
> about "git amend," I don't think that it's going to be particularly
> successful if we try to capture all this stuff in the commit message
> and metadata, because it's tough to guarantee that *all* this data
> would be correctly captured at commit time, and you can't revise it
> after the commit gets pushed upstream.

Perhaps `git notes` could be something used to annotate these:

http://www.kernel.org/pub/software/scm/git/docs/git-notes.html

Regards,

David
--
David Christensen
End Point Corporation
david(at)endpoint(dot)com

On 06/24/2011 04:52 PM, Bruce Momjian wrote:
> That tagging is basically what I do on my first pass through the release
> notes. For the gory details:
>
> http://momjian.us/main/blogs/pgblog/2009.html#March_25_2009
>

Excellent summary of the process I was trying to suggest might be
improved; the two most relevant bits:

3 remove insignificant items 2.7k 1 day
4 research and reword items 1k 5 days

Some sort of tagging to identify feature changes should drive down the
time spent on filtering insignificant items. And the person doing the
commit already has the context you are acquiring later as "research"
here. Would suggesting they try to write a short description at commit
time drive it and the "reword" phase time down significantly? Can't say
for sure, but I wanted to throw the idea out for
consideration--particularly since solving it well ends up making some of
this other derived data people would like to see a lot easier to
generate too.

--
Greg Smith 2ndQuadrant US greg(at)2ndQuadrant(dot)com Baltimore, MD
PostgreSQL Training, Services, and 24x7 Support www.2ndQuadrant.us

Greg Smith wrote:
> On 06/24/2011 04:52 PM, Bruce Momjian wrote:
> > That tagging is basically what I do on my first pass through the release
> > notes. For the gory details:
> >
> > http://momjian.us/main/blogs/pgblog/2009.html#March_25_2009
> >
>
> Excellent summary of the process I was trying to suggest might be
> improved; the two most relevant bits:
>
> 3 remove insignificant items 2.7k 1 day
> 4 research and reword items 1k 5 days
>
>
> Some sort of tagging to identify feature changes should drive down the
> time spent on filtering insignificant items. And the person doing the
> commit already has the context you are acquiring later as "research"
> here. Would suggesting they try to write a short description at commit
> time drive it and the "reword" phase time down significantly? Can't say
> for sure, but I wanted to throw the idea out for
> consideration--particularly since solving it well ends up making some of
> this other derived data people would like to see a lot easier to
> generate too.

Most of those five days is tracking down commits where I can't figure
out the user-visible change, or if there is one, and wording things to
be in a consistent voice. Git does allow me to look those up much
faster than CVS.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On 06/24/2011 03:28 PM, Christopher Browne wrote:
> I expect that the correlation between commit and [various parties] is
> something that will need to take place outside git.
>

Agreed on everything except the "Author" information that is already
being placed into each commit. The right data is already going into
there, all it would take is some small amount of tagging to make it
easier to extract programatically.

> The existing CommitFest data goes quite a long ways towards capturing
> interesting information (with the likely exception of sponsorship);
> what it's missing, at this point, is a capture of what commit or
> commits wound up drawing the proposed patch into the official code
> base.

The main problem with driving this from the CommitFest app is that not
every feature ends up in there. Committers who commit their own work
are one source of those. Commits for bug fixes that end up being
notable enough to go into the release notes are another.

I agree it would be nice if every entry marked as "Committed" in the CF
app included a final link to the message ID of the commit closing it.
But since I don't ever see that being the complete data set, I find it
hard to justify enforcing that work. And the ability to operate
programatically on the output from "git log" is a slightly easier path
to walk down than extracting the same from the CF app, you avoid one
pre-processing step: extracting the right entries in the database to
get a list of commit IDs.

--
Greg Smith 2ndQuadrant US greg(at)2ndQuadrant(dot)com Baltimore, MD
PostgreSQL Training, Services, and 24x7 Support www.2ndQuadrant.us

On 06/24/2011 03:21 PM, Robert Haas wrote:
> If I were attacking this problem, I'd be inclined to make a web
> application that lists all the commits in a format roughly similar to
> the git API, and then lets you tag each commit with tags from some
> list (feature, bug-fix, revert, repair-of-previous-commit, etc.).
> Some of the tagging (e.g. docs-only) could probably even be done
> automatically. Then somebody could go through once a month and update
> all the tags. I'd be more more willing to volunteer to do that than I
> would be to trying to get the right metadata tag in every commit...
>

I tend not to think in terms of solutions that involve web applications
because I never build them, but this seems like a useful approach to
consider. Given that the list of tags is pretty static, I could see a
table with a line for each commit, and a series of check boxes in
columns for each tag next to it. Then you just click on each of the
tags that apply to that line.

Once that was done, increasing the amount of smarts that go into
pre-populating which boxes are already filled in could then happen, with
"docs only" being the easiest one to spot. A really smart
implementation here might even eventually make a good guess for "bug
fix" too, based on whether a bunch of similar commits happened to other
branches around the same time. Everyone is getting better lately at
noting the original SHA1 when fixing a mistake too, so being able to
identify "repair" seems likely when that's observed.

This approach would pull the work from being at commit time, but it
would still be easier to do incrementally and to distribute the work
around than what's feasible right now. Release note prep takes critical
project contributors a non-trivial amount of time, this would let anyone
who felt like tagging things for an hour help with the early stages of
that. And it would provide a functional source for the metadata I've
been searching for too, to drive all this derived data about sponsors etc.

Disclaimer: as a person who does none of this work currently, my
suggestions are strictly aimed to inspire those who do in a direction
that might makes things easier for them. I can get the sponsor stuff
I've volunteered to work on finished regardless. I just noticed what
seems like it could be a good optimization over here while I was working
on that.

--
Greg Smith 2ndQuadrant US greg(at)2ndQuadrant(dot)com Baltimore, MD
PostgreSQL Training, Services, and 24x7 Support www.2ndQuadrant.us

Greg Smith wrote:
> I tend not to think in terms of solutions that involve web applications
> because I never build them, but this seems like a useful approach to
> consider. Given that the list of tags is pretty static, I could see a
> table with a line for each commit, and a series of check boxes in
> columns for each tag next to it. Then you just click on each of the
> tags that apply to that line.
>
> Once that was done, increasing the amount of smarts that go into
> pre-populating which boxes are already filled in could then happen, with
> "docs only" being the easiest one to spot. A really smart
> implementation here might even eventually make a good guess for "bug
> fix" too, based on whether a bunch of similar commits happened to other
> branches around the same time. Everyone is getting better lately at
> noting the original SHA1 when fixing a mistake too, so being able to
> identify "repair" seems likely when that's observed.
>
> This approach would pull the work from being at commit time, but it
> would still be easier to do incrementally and to distribute the work
> around than what's feasible right now. Release note prep takes critical
> project contributors a non-trivial amount of time, this would let anyone
> who felt like tagging things for an hour help with the early stages of
> that. And it would provide a functional source for the metadata I've
> been searching for too, to drive all this derived data about sponsors etc.

We could have the items put into release note categories and have a
button that marks incompatibilties.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On Fri, Jun 24, 2011 at 7:51 PM, Greg Smith <greg(at)2ndquadrant(dot)com> wrote:
> On 06/24/2011 03:28 PM, Christopher Browne wrote:
>> I expect that the correlation between commit and [various parties] is
>> something that will need to take place outside git.
>
> Agreed on everything except the "Author" information that is already being
> placed into each commit.  The right data is already going into there, all it
> would take is some small amount of tagging to make it easier to extract
> programatically.

Yeah, I think we should seriously consider doing something about that.

>> The existing CommitFest data goes quite a long ways towards capturing
>> interesting information (with the likely exception of sponsorship);
>> what it's missing, at this point, is a capture of what commit or
>> commits wound up drawing the proposed patch into the official code
>> base.
>
> The main problem with driving this from the CommitFest app is that not every
> feature ends up in there.  Committers who commit their own work are one
> source of those.  Commits for bug fixes that end up being notable enough to
> go into the release notes are another.

Yep.

> I agree it would be nice if every entry marked as "Committed" in the CF app
> included a final link to the message ID of the commit closing it.  But since
> I don't ever see that being the complete data set, I find it hard to justify
> enforcing that work.  And the ability to operate programatically on the
> output from "git log" is a slightly easier path to walk down than extracting
> the same from the CF app, you avoid one pre-processing step:  extracting the
> right entries in the database to get a list of commit IDs.

Yep.

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

On Fri, 24 Jun 2011 13:42:04 -0400
Robert Haas <robertmhaas(at)gmail(dot)com> wrote:

> As for annotating the commit messages, I think something like:
>
> Reporter: Sam Jones
> Author: Beverly Smith
> Author: Jim Davids
> Reviewer: Fred Block
> Reviewer: Pauline Andrews

Can I just toss in one little note from the sidelines? Various other
projects (Linux kernel at the top of the list) have adopted tags like
Reported-by and Reviewed-by for metadata like this. (Authorship lives in
git itself, with additional authors sometimes ambiguously indicated with
additional Signed-off-by lines). There are tools out there which make use
of those tags now. It would seem that, in the absence of a reason to make
up your own tags, it might make sense to be consistent with other projects?

Thanks,

jon

On Mon, Jun 27, 2011 at 11:49 AM, Jonathan Corbet <corbet(at)lwn(dot)net> wrote:
> On Fri, 24 Jun 2011 13:42:04 -0400
> Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
>
>> As for annotating the commit messages, I think something like:
>>
>> Reporter: Sam Jones
>> Author: Beverly Smith
>> Author: Jim Davids
>> Reviewer: Fred Block
>> Reviewer: Pauline Andrews
>
> Can I just toss in one little note from the sidelines?  Various other
> projects (Linux kernel at the top of the list) have adopted tags like
> Reported-by and Reviewed-by for metadata like this.  (Authorship lives in
> git itself, with additional authors sometimes ambiguously indicated with
> additional Signed-off-by lines).  There are tools out there which make use
> of those tags now.  It would seem that, in the absence of a reason to make
> up your own tags, it might make sense to be consistent with other projects?

I'm not averse to inventing our own tags that fit our particular
needs, but I don't think it would be a bad idea to maximize the
intersection of what we do with what other people do.

I think the biggest difference is probably that we (or at least I)
don't really like the idea of Signed-off-by, and certainly not as a
way of ambiguously indicating additional authors. Many patches are
collaborative efforts, and the metadata should make that clear.

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

[ I'm a bit late to the party on this thread, but anyway: ]

Robert Haas <robertmhaas(at)gmail(dot)com> writes:
> On Fri, Jun 24, 2011 at 7:51 PM, Greg Smith <greg(at)2ndquadrant(dot)com> wrote:
>> On 06/24/2011 03:28 PM, Christopher Browne wrote:
>>> I expect that the correlation between commit and [various parties] is
>>> something that will need to take place outside git.

>> Agreed on everything except the "Author" information that is already being
>> placed into each commit. The right data is already going into there, all it
>> would take is some small amount of tagging to make it easier to extract
>> programatically.

> Yeah, I think we should seriously consider doing something about that.

My recollection is that we considered and rejected using git's Author:
field, primarily because it doesn't scale to multiple authors. We might
be more accustomed to git now than we were last year, but it still won't
scale.

I wouldn't have a problem with establishing a convention that we
write credits in commit messages in a more standardized way, ie put
something like "Author: Joe Blow <joe(at)blow(dot)nom>" in the body of the
commit message. However, the points that were raised about commit
messages being effectively uncorrectable after-the-fact seem to me
to put a big crimp in the idea of using that as the primary source
of credit information. We'd still need something like the web app
Robert described in <BANLkTimOxDA08qM4LSH4QjA3YZtyuuewsA(at)mail(dot)gmail(dot)com>
to allow correction of the info.

There's a point I didn't see raised with respect to Greg's main original
idea, that the commit message should contain text that could be used
directly in the release notes. Namely, that the commit messages are
written for a different audience than the release notes are, and so it
is perfectly natural for them to need considerable massaging to create
release notes. Whoever is doing the release notes also has to exert
a good deal of editorial judgement to phrase all the notes in similar
voices, allot an appropriate amount of space to each depending on the
user-visible impact, etc. That work would still have to be done even
if each committer always attempted to provide release-note-ready text.
So I'm not sure that much work would get saved this way.

regards, tom lane

On Saturday, July 02, 2011 06:10:43 AM Tom Lane wrote:
> I wouldn't have a problem with establishing a convention that we
> write credits in commit messages in a more standardized way, ie put
> something like "Author: Joe Blow <joe(at)blow(dot)nom>" in the body of the
> commit message. However, the points that were raised about commit
> messages being effectively uncorrectable after-the-fact seem to me
> to put a big crimp in the idea of using that as the primary source
> of credit information. We'd still need something like the web app
> Robert described in <BANLkTimOxDA08qM4LSH4QjA3YZtyuuewsA(at)mail(dot)gmail(dot)com>
> to allow correction of the info.
There are git notes which you can attach to a commit after the fact... I like
the fact that they would keep the information in the repository (where they
seem to belong).

Andres

On Sat, Jul 2, 2011 at 10:19 AM, Andres Freund <andres(at)anarazel(dot)de> wrote:
> On Saturday, July 02, 2011 06:10:43 AM Tom Lane wrote:
>> I wouldn't have a problem with establishing a convention that we
>> write credits in commit messages in a more standardized way, ie put
>> something like "Author: Joe Blow <joe(at)blow(dot)nom>" in the body of the
>> commit message.  However, the points that were raised about commit
>> messages being effectively uncorrectable after-the-fact seem to me
>> to put a big crimp in the idea of using that as the primary source
>> of credit information.  We'd still need something like the web app
>> Robert described in <BANLkTimOxDA08qM4LSH4QjA3YZtyuuewsA(at)mail(dot)gmail(dot)com>
>> to allow correction of the info.
> There are git notes which you can attach to a commit after the fact... I like
> the fact that they would keep the information in the repository (where they
> seem to belong).

Yeah, but I think it's still basically append-only, which is kind of a
nuisance, and it means they can only be updated by committers, which
is not particularly helpful from my point of view.

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

On Sat, Jul 02, 2011 at 03:45:03PM -0400, Robert Haas wrote:
> > There are git notes which you can attach to a commit after the fact... I like
> > the fact that they would keep the information in the repository (where they
> > seem to belong).
>
> Yeah, but I think it's still basically append-only, which is kind of a
> nuisance, and it means they can only be updated by committers, which
> is not particularly helpful from my point of view.

The documentation says:

"This command allows you to add/remove notes to/from objects, without
changing the objects themselves."

So it doesn't appear append only. I think the idea is that every object
can have one note. How that works with versioning I have no idea.

Have a nice day,
--
Martijn van Oosterhout <kleptog(at)svana(dot)org> http://svana.org/kleptog/
> Patriotism is when love of your own people comes first; nationalism,
> when hate for people other than your own comes first.
> - Charles de Gaulle

Martijn van Oosterhout <kleptog(at)svana(dot)org> writes:
> On Sat, Jul 02, 2011 at 03:45:03PM -0400, Robert Haas wrote:
>>> There are git notes which you can attach to a commit after the fact... I like
>>> the fact that they would keep the information in the repository (where they
>>> seem to belong).

>> Yeah, but I think it's still basically append-only, which is kind of a
>> nuisance, and it means they can only be updated by committers, which
>> is not particularly helpful from my point of view.

> The documentation says:
> "This command allows you to add/remove notes to/from objects, without
> changing the objects themselves."

> So it doesn't appear append only. I think the idea is that every object
> can have one note. How that works with versioning I have no idea.

A look at the git-notes man page says that you can only have one note
per commit, but you can edit that note, and git does track the revision
history of each note.

I think that we should adopt "git notes" as a better solution than
making dummy whitespace changes when we want to put a commit-message
correction into the commit history (you listening, Bruce?).

But as Robert says, this still leaves the committers as the gatekeepers
for the information, so it's not clear to me that this is a good way to
solve the problems that Greg was talking about originally. I'd rather
have a solution that offloads the work from the committers.

regards, tom lane

On Sunday, July 03, 2011 06:46:15 PM Tom Lane wrote:
> A look at the git-notes man page says that you can only have one note
> per commit, but you can edit that note, and git does track the revision
> history of each note.
>
> I think that we should adopt "git notes" as a better solution than
> making dummy whitespace changes when we want to put a commit-message
> correction into the commit history (you listening, Bruce?).
There is git commit --allow-empty btw

> But as Robert says, this still leaves the committers as the gatekeepers
> for the information, so it's not clear to me that this is a good way to
> solve the problems that Greg was talking about originally. I'd rather
> have a solution that offloads the work from the committers.
I don't think its that hard to write a hook which allows notes changes for a
different set of people than source changes.
Whether the people wanting to annotate commits are ok with using git I do not
know.

Andres

On Sun, Jul 3, 2011 at 20:04, Andres Freund <andres(at)anarazel(dot)de> wrote:
> On Sunday, July 03, 2011 06:46:15 PM Tom Lane wrote:
>> A look at the git-notes man page says that you can only have one note
>> per commit, but you can edit that note, and git does track the revision
>> history of each note.
>>
>> I think that we should adopt "git notes" as a better solution than
>> making dummy whitespace changes when we want to put a commit-message
>> correction into the commit history (you listening, Bruce?).

That sounds like a reasonable use for git notes.

> There is git commit --allow-empty btw
>
>> But as Robert says, this still leaves the committers as the gatekeepers
>> for the information, so it's not clear to me that this is a good way to
>> solve the problems that Greg was talking about originally.  I'd rather
>> have a solution that offloads the work from the committers.
> I don't think its that hard to write a hook which allows notes changes for a
> different set of people than source changes.
> Whether the people wanting to annotate commits are ok with using git I do not
> know.

If you want a different group of people to maintain it, then why force
it into the same repository in the first place? Having to write hooks
to work around things with that seems to be solving the wrong problem,
imho.

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

On Sunday, July 03, 2011 09:18:52 PM Magnus Hagander wrote:
> On Sun, Jul 3, 2011 at 20:04, Andres Freund <andres(at)anarazel(dot)de> wrote:
> > On Sunday, July 03, 2011 06:46:15 PM Tom Lane wrote:
> >> A look at the git-notes man page says that you can only have one note
> >> per commit, but you can edit that note, and git does track the revision
> >> history of each note.
> > I don't think its that hard to write a hook which allows notes changes
> > for a different set of people than source changes.
> > Whether the people wanting to annotate commits are ok with using git I do
> > not know.
>
> If you want a different group of people to maintain it, then why force
> it into the same repository in the first place? Having to write hooks
> to work around things with that seems to be solving the wrong problem,
> imho.
Because imho the information who worked on a patch belongs alongside the
patch. I can't forsee a really useful usage of that information without the
commit alongside...

Andres

Tom Lane wrote:
> Martijn van Oosterhout <kleptog(at)svana(dot)org> writes:
> > On Sat, Jul 02, 2011 at 03:45:03PM -0400, Robert Haas wrote:
> >>> There are git notes which you can attach to a commit after the fact... I like
> >>> the fact that they would keep the information in the repository (where they
> >>> seem to belong).
>
> >> Yeah, but I think it's still basically append-only, which is kind of a
> >> nuisance, and it means they can only be updated by committers, which
> >> is not particularly helpful from my point of view.
>
> > The documentation says:
> > "This command allows you to add/remove notes to/from objects, without
> > changing the objects themselves."
>
> > So it doesn't appear append only. I think the idea is that every object
> > can have one note. How that works with versioning I have no idea.
>
> A look at the git-notes man page says that you can only have one note
> per commit, but you can edit that note, and git does track the revision
> history of each note.
>
> I think that we should adopt "git notes" as a better solution than
> making dummy whitespace changes when we want to put a commit-message
> correction into the commit history (you listening, Bruce?).

Yes, I heard. I don't think I have done that since we moved to git.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

Excerpts from Andres Freund's message of sáb jul 02 10:19:07 -0400 2011:
> On Saturday, July 02, 2011 06:10:43 AM Tom Lane wrote:
> > I wouldn't have a problem with establishing a convention that we
> > write credits in commit messages in a more standardized way, ie put
> > something like "Author: Joe Blow <joe(at)blow(dot)nom>" in the body of the
> > commit message. However, the points that were raised about commit
> > messages being effectively uncorrectable after-the-fact seem to me
> > to put a big crimp in the idea of using that as the primary source
> > of credit information. We'd still need something like the web app
> > Robert described in <BANLkTimOxDA08qM4LSH4QjA3YZtyuuewsA(at)mail(dot)gmail(dot)com>
> > to allow correction of the info.
> There are git notes which you can attach to a commit after the fact... I like
> the fact that they would keep the information in the repository (where they
> seem to belong).

Does anyone know how do git notes propagate from one repo to another?
I'm not sure that they are copied on "git push".

If they don't, they would be pretty useless, so I assume there must be a
way.

--
Álvaro Herrera <alvherre(at)commandprompt(dot)com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Alvaro Herrera <alvherre(at)commandprompt(dot)com> writes:
> Does anyone know how do git notes propagate from one repo to another?
> I'm not sure that they are copied on "git push".

> If they don't, they would be pretty useless, so I assume there must be a
> way.

[ googles... ] According to
http://progit.org/2010/08/25/notes.html
it is possible, but neither push nor pull is automatic, which means
they're probably next door to useless for us. Oh well.

regards, tom lane