Thread: 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@2ndQuadrant.com Baltimore, MD PostgreSQL Training, Services, and 24x7 Support www.2ndQuadrant.us
On Fri, Jun 24, 2011 at 5:15 PM, Greg Smith <greg@2ndquadrant.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@2ndquadrant.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@2ndQuadrant.com Baltimore, MD PostgreSQL Training, Services, and 24x7 Support www.2ndQuadrant.us
On Fri, Jun 24, 2011 at 2:47 PM, Greg Smith <greg@2ndquadrant.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@2ndquadrant.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@2ndquadrant.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@momjian.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@2ndquadrant.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@endpoint.com
On 06/24/2011 04:52 PM, Bruce Momjian wrote: <blockquote cite="mid:201106242052.p5OKqj319301@momjian.us" type="cite">Thattagging is basically what I do on my first pass through the release<br /><pre wrap="">notes. For the gorydetails: <a class="moz-txt-link-freetext" href="http://momjian.us/main/blogs/pgblog/2009.html#March_25_2009">http://momjian.us/main/blogs/pgblog/2009.html#March_25_2009</a> </pre></blockquote><br/> Excellent summary of the process I was trying to suggest might be improved; the two most relevantbits:<br /><br /><table border="1" summary=""><tbody><tr><td>3</td><td>remove insignificant items</td><td>2.7k</td><td>1day</td></tr><tr><td>4</td><td>research and reword items</td><td>1k</td><td>5 days</td></tr></tbody></table><br/> Some sort of tagging to identify feature changes should drive down the time spent onfiltering 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 timedown significantly? Can't say for sure, but I wanted to throw the idea out for consideration--particularly since solvingit well ends up making some of this other derived data people would like to see a lot easier to generate too.<br /><br/><pre class="moz-signature" cols="72">-- Greg Smith 2ndQuadrant US <a class="moz-txt-link-abbreviated" href="mailto:greg@2ndQuadrant.com">greg@2ndQuadrant.com</a> Baltimore, MD PostgreSQL Training, Services, and 24x7 Support <a class="moz-txt-link-abbreviated" href="http://www.2ndQuadrant.us">www.2ndQuadrant.us</a> </pre>
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@momjian.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@2ndQuadrant.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@2ndQuadrant.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@momjian.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@2ndquadrant.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 Mon, Jun 27, 2011 at 11:49 AM, Jonathan Corbet <corbet@lwn.net> wrote: > On Fri, 24 Jun 2011 13:42:04 -0400 > Robert Haas <robertmhaas@gmail.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
On Fri, 24 Jun 2011 13:42:04 -0400 Robert Haas <robertmhaas@gmail.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
[ I'm a bit late to the party on this thread, but anyway: ] Robert Haas <robertmhaas@gmail.com> writes: > On Fri, Jun 24, 2011 at 7:51 PM, Greg Smith <greg@2ndquadrant.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@blow.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@mail.gmail.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@blow.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@mail.gmail.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@anarazel.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@blow.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@mail.gmail.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@svana.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@svana.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@anarazel.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@anarazel.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@svana.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@momjian.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@blow.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@mail.gmail.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@commandprompt.com> The PostgreSQL Company - Command Prompt, Inc. PostgreSQL Replication, Consulting, Custom Development, 24x7 support
Alvaro Herrera <alvherre@commandprompt.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