Thread: Patch to git_changelog for release note creation
I would like to apply the attached patch to git_changelog for use in
creating the major release notes. I specifically added these flags:
--author-after Show author after the commit
--master-only Show commits made exclusively to the master branch
--reverse-order Show commits in reverse date order
The default output is unaffected.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
diff --git a/src/tools/git_changelog b/src/tools/git_changelog
new file mode 100755
index af76f6d..3cd5af4
*** a/src/tools/git_changelog
--- b/src/tools/git_changelog
*************** my @BRANCHES = qw(master REL9_0_STABLE R
*** 43,51 ****
# Might want to make this parameter user-settable.
my $timestamp_slop = 600;
my $post_date = 0;
my $since;
! Getopt::Long::GetOptions('post-date' => \$post_date,
'since=s' => \$since) || usage();
usage() if @ARGV;
--- 43,60 ----
# Might want to make this parameter user-settable.
my $timestamp_slop = 600;
+ my $author_after = 0;
my $post_date = 0;
+ my $master_only = 0;
+ my $reverse_order = 0;
my $since;
! my @output_buffer;
! my $output_line = '';
!
! Getopt::Long::GetOptions('author-after' => \$author_after,
! 'master-only' => \$master_only,
! 'post-date' => \$post_date,
! 'reverse-order' => \$reverse_order,
'since=s' => \$since) || usage();
usage() if @ARGV;
*************** while (1) {
*** 193,211 ****
last if !defined $best_branch;
my $winner =
$all_commits_by_branch{$best_branch}->[$position{$best_branch}];
! printf "Author: %s\n", $winner->{'author'};
! foreach my $c (@{$winner->{'commits'}}) {
! printf "Branch: %s", $c->{'branch'};
! if (defined $c->{'last_tag'}) {
! printf " Release: %s", $c->{'last_tag'};
! }
! printf " [%s] %s\n", substr($c->{'commit'}, 0, 9), $c->{'date'};
}
! print "Commit-Order-Inversions: $best_inversions\n"
! if $best_inversions != 0;
! print "\n";
! print $winner->{'message'};
! print "\n";
$winner->{'done'} = 1;
for my $branch (@BRANCHES) {
my $leader = $all_commits_by_branch{$branch}->[$position{$branch}];
--- 202,229 ----
last if !defined $best_branch;
my $winner =
$all_commits_by_branch{$best_branch}->[$position{$best_branch}];
!
! # check for master-only
! if (! $master_only || ($winner->{'commits'}[0]->{'branch'} eq 'master' &&
! @{$winner->{'commits'}} == 1)) {
! output_entry("Author: %s\n", $winner->{'author'}) if (! $author_after);
! foreach my $c (@{$winner->{'commits'}}) {
! output_entry("Branch: %s ", $c->{'branch'}) if (! $master_only);
! if (defined $c->{'last_tag'}) {
! output_entry("Release: %s ", $c->{'last_tag'});
! }
! output_entry("[%s] %s\n", substr($c->{'commit'}, 0, 9), $c->{'date'});
! }
! output_entry("Commit-Order-Inversions: $best_inversions\n")
! if $best_inversions != 0;
! output_entry("\n");
! output_entry("%s", $winner->{'message'});
! output_entry("%s\n", $winner->{'author'}) if ($author_after);
! output_entry("\n");
! unshift(@output_buffer, $output_line) if ($reverse_order);
! $output_line = '';
}
!
$winner->{'done'} = 1;
for my $branch (@BRANCHES) {
my $leader = $all_commits_by_branch{$branch}->[$position{$branch}];
*************** while (1) {
*** 216,221 ****
--- 234,241 ----
}
}
+ print @output_buffer if ($reverse_order);
+
sub push_commit {
my ($c) = @_;
my $ht = hash_commit($c);
*************** sub parse_datetime {
*** 274,284 ****
return $gm - $tzoffset;
}
sub usage {
print STDERR <<EOM;
! Usage: git_changelog [--post-date/-p] [--since=SINCE]
! --post-date Show branches made after a commit occurred
! --since Print only commits dated since SINCE
EOM
exit 1;
}
--- 294,316 ----
return $gm - $tzoffset;
}
+ sub output_entry {
+ if (! $reverse_order) {
+ printf(@_);
+ } else {
+ my $fmt = shift;
+ $output_line .= sprintf($fmt, @_);
+ }
+ }
+
sub usage {
print STDERR <<EOM;
! Usage: git_changelog [--author-after/-a] [--master-only/-m] [--post-date/-p] [--reverse-order/-r] [--since=SINCE]
! --author-after Show author after the commit
! --master-only Show commits made exclusively to the master branch
! --post-date Show branches made after a commit occurred
! --reverse-order Show commits in reverse date order
! --since Print only commits dated since SINCE
EOM
exit 1;
}
Bruce Momjian <bruce@momjian.us> writes:
> I would like to apply the attached patch to git_changelog for use in
> creating the major release notes. I specifically added these flags:
> --author-after Show author after the commit
> --master-only Show commits made exclusively to the master branch
> --reverse-order Show commits in reverse date order
Your implementation of --master-only seems really grotty. Can't you
just add "origin/master" to the basic git log command?
As for --reverse-order, what's that got to do with preparing release
notes? The end product shouldn't be particularly sensitive to the order
of commit of features ...
regards, tom lane
On Tue, Mar 15, 2011 at 9:59 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > Bruce Momjian <bruce@momjian.us> writes: >> I would like to apply the attached patch to git_changelog for use in >> creating the major release notes. I specifically added these flags: > >> --author-after Show author after the commit >> --master-only Show commits made exclusively to the master branch >> --reverse-order Show commits in reverse date order > > Your implementation of --master-only seems really grotty. Can't you > just add "origin/master" to the basic git log command? No, he wants to exclude things that were back-patched. But I agree it's kind of grotty. Imagine you are preparing release notes for a minor release. Now you will want all the back-branch commits, but not the ones that were only committed to master. I think rather than inserting piecemeal hacks like this, we should try to be a bit more generic, something like -x branchname to exclude any commit that touches the named branch, and -o branchname to restrict the output to commits that touch ONLY the named branch, or something along those lines. > As for --reverse-order, what's that got to do with preparing release > notes? The end product shouldn't be particularly sensitive to the order > of commit of features ... True... And I can't say I like --author-only much, either. I understand its use for preparing release notes, but I don't really like the idea of adding something to the tool that solves 1% of the problem of automating release note generation. I'm afraid that in a few major releases the documented method of preparing release notes will look like this: src/tools/git_changelong --master-only --author-after --reverse-order --omit-commit-ids --omit-dates --another-switch-bruce-invented --more-magic --additional-sorcery --fix-other-things --some-more-tweaks --etc-etc-etc At which point we will have successfully automated roughly 8% of the work of release note generation and reduced the source code to utter unmaintainability. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Tom Lane wrote: > Bruce Momjian <bruce@momjian.us> writes: > > I would like to apply the attached patch to git_changelog for use in > > creating the major release notes. I specifically added these flags: > > > --author-after Show author after the commit > > --master-only Show commits made exclusively to the master branch > > --reverse-order Show commits in reverse date order > > Your implementation of --master-only seems really grotty. Can't you > just add "origin/master" to the basic git log command? I need commits that went exclusively to the master branch --- a commit the goes to master and a subbranch should not appear because it was already present in a minor release. > As for --reverse-order, what's that got to do with preparing release > notes? The end product shouldn't be particularly sensitive to the order > of commit of features ... Many commits reference earlier commits so having them in oldest-first order makes the aggregation of those commits easier. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
Robert Haas wrote: > On Tue, Mar 15, 2011 at 9:59 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > > Bruce Momjian <bruce@momjian.us> writes: > >> I would like to apply the attached patch to git_changelog for use in > >> creating the major release notes. ?I specifically added these flags: > > > >> ? ? --author-after ?Show author after the commit > >> ? ? --master-only ? Show commits made exclusively to the master branch > >> ? ? --reverse-order Show commits in reverse date order > > > > Your implementation of --master-only seems really grotty. ?Can't you > > just add "origin/master" to the basic git log command? > > No, he wants to exclude things that were back-patched. But I agree > it's kind of grotty. Imagine you are preparing release notes for a > minor release. Now you will want all the back-branch commits, but not > the ones that were only committed to master. I think rather than > inserting piecemeal hacks like this, we should try to be a bit more > generic, something like -x branchname to exclude any commit that > touches the named branch, and -o branchname to restrict the output to > commits that touch ONLY the named branch, or something along those > lines. Sure, that works for me. We can always improve what I have done. > > As for --reverse-order, what's that got to do with preparing release > > notes? ?The end product shouldn't be particularly sensitive to the order > > of commit of features ... > > True... > > And I can't say I like --author-only much, either. I understand its > use for preparing release notes, but I don't really like the idea of > adding something to the tool that solves 1% of the problem of > automating release note generation. I'm afraid that in a few major > releases the documented method of preparing release notes will look > like this: > > src/tools/git_changelong --master-only --author-after --reverse-order > --omit-commit-ids --omit-dates --another-switch-bruce-invented > --more-magic --additional-sorcery --fix-other-things > --some-more-tweaks --etc-etc-etc > > At which point we will have successfully automated roughly 8% of the > work of release note generation and reduced the source code to utter > unmaintainability. Well, I need it for the release notes now, so either I make my own version, tieing release note generation even closer to me, or we add some flags and keep improving the tool. Bottom line: I need to start the release notes today --- I can hack my own version and we can revisit this later, which I am afraid will be in one year, or we can just add what I have and we can keep hacking on it as needed. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
Bruce Momjian wrote: > Bottom line: I need to start the release notes today --- I can hack my > own version and we can revisit this later, which I am afraid will be in > one year, or we can just add what I have and we can keep hacking on it > as needed. Oh, one more thing. pgcvslog was added to src/tools by me for release note generation. I asked for git_changelog for release note generation. Now saying we don't want to modify git_changelog because it would be too tied to release note generation seems silly because no one wanted the tool until I added a CVS version for release notes. As proof, pgcvslog output exactly the format I needed for release notes, and had no option for any other output format. As I understand it now, git_changelog is replacing pgcvslog and cvs2cl. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
On Tue, Mar 15, 2011 at 10:25 AM, Bruce Momjian <bruce@momjian.us> wrote: > Robert Haas wrote: >> On Tue, Mar 15, 2011 at 9:59 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: >> > Bruce Momjian <bruce@momjian.us> writes: >> >> I would like to apply the attached patch to git_changelog for use in >> >> creating the major release notes. ?I specifically added these flags: >> > >> >> ? ? --author-after ?Show author after the commit >> >> ? ? --master-only ? Show commits made exclusively to the master branch >> >> ? ? --reverse-order Show commits in reverse date order >> > >> > Your implementation of --master-only seems really grotty. ?Can't you >> > just add "origin/master" to the basic git log command? >> >> No, he wants to exclude things that were back-patched. But I agree >> it's kind of grotty. Imagine you are preparing release notes for a >> minor release. Now you will want all the back-branch commits, but not >> the ones that were only committed to master. I think rather than >> inserting piecemeal hacks like this, we should try to be a bit more >> generic, something like -x branchname to exclude any commit that >> touches the named branch, and -o branchname to restrict the output to >> commits that touch ONLY the named branch, or something along those >> lines. > > Sure, that works for me. We can always improve what I have done. > >> > As for --reverse-order, what's that got to do with preparing release >> > notes? ?The end product shouldn't be particularly sensitive to the order >> > of commit of features ... >> >> True... >> >> And I can't say I like --author-only much, either. I understand its >> use for preparing release notes, but I don't really like the idea of >> adding something to the tool that solves 1% of the problem of >> automating release note generation. I'm afraid that in a few major >> releases the documented method of preparing release notes will look >> like this: >> >> src/tools/git_changelong --master-only --author-after --reverse-order >> --omit-commit-ids --omit-dates --another-switch-bruce-invented >> --more-magic --additional-sorcery --fix-other-things >> --some-more-tweaks --etc-etc-etc >> >> At which point we will have successfully automated roughly 8% of the >> work of release note generation and reduced the source code to utter >> unmaintainability. > > Well, I need it for the release notes now, so either I make my own > version, tieing release note generation even closer to me, or we add > some flags and keep improving the tool. > > Bottom line: I need to start the release notes today --- I can hack my > own version and we can revisit this later, which I am afraid will be in > one year, or we can just add what I have and we can keep hacking on it > as needed. The release note generation is tied to you because you're the guy who writes the release notes, not for any tools reason. You seem to believe that someone else would want the flags; I don't believe that at all. I would do the whole thing differently; the need for these particular things is because Bruce wants to do it a certain way, not because that's the only way to do it. I'm happy to add flags to git_changelog that are potentially useful to more than one person, but I don't think you've demonstrated that's the case here, which is why I think you maintaining your own version is perfectly fine and appropriate. I'm happy to see about adding -x/-o flags if we all agree that's useful, but maybe better names are in order. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Robert Haas <robertmhaas@gmail.com> writes:
> No, he wants to exclude things that were back-patched. But I agree
> it's kind of grotty. Imagine you are preparing release notes for a
> minor release. Now you will want all the back-branch commits, but not
> the ones that were only committed to master. I think rather than
> inserting piecemeal hacks like this, we should try to be a bit more
> generic, something like -x branchname to exclude any commit that
> touches the named branch, and -o branchname to restrict the output to
> commits that touch ONLY the named branch, or something along those
> lines.
OK, but if we're going to try to design this more generally, let's keep
in mind what the *actual* workflow is. We don't prepare release notes
for one back branch in isolation. Every update release for lo these many
years has been for multiple back branches concurrently, with usually
mostly the same patches applied to all of them. I shouldn't speak for
Bruce, but when I do it, I make one set of release notes covering all
the back-patched patches. After I'm happy with the presentation of
that, I copy it into each back branch's SGML section and strip out any
items not relevant to that branch. The output of git_changelog is
already pretty well suited to that workflow, although it would be handy
to have a switch to exclude master-only commits.
So I'd vote for having both --master-only and its inverse
--ignore-master, but I'm not sure we need anything more general
than that.
regards, tom lane
Robert Haas wrote: > > Bottom line: ?I need to start the release notes today --- I can hack my > > own version and we can revisit this later, which I am afraid will be in > > one year, or we can just add what I have and we can keep hacking on it > > as needed. > > The release note generation is tied to you because you're the guy who > writes the release notes, not for any tools reason. You seem to > believe that someone else would want the flags; I don't believe that > at all. I would do the whole thing differently; the need for these > particular things is because Bruce wants to do it a certain way, not > because that's the only way to do it. I'm happy to add flags to > git_changelog that are potentially useful to more than one person, but > I don't think you've demonstrated that's the case here, which is why I > think you maintaining your own version is perfectly fine and > appropriate. I believe I was clear why the reverse order is needed (progressive commits), and the author goes at the end of the release note item, hence my flag to move it. I can hack up something to move the author but it seems much easier in the tool, and I do believe having the author where it will appear in our release notes is helpful, unless we are thinking of changing the format of our release notes. Does someone else want to generate the major release notes this time? At this point I will just make my own version and if someone else needs flags, _they_ can add them and argue about them. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
I wrote:
> So I'd vote for having both --master-only and its inverse
> --ignore-master, but I'm not sure we need anything more general
> than that.
On second thought ... one big problem with --master-only is that
it's useful only to the extent that you trust git_changelog to
have matched up master and back-branch commits. The tool is definitely
not perfect about that: sometimes related commits will not have
identical texts (this would be the committer's fault) or the timestamps
are not close enough (which can be git's fault, because of the way git
pull works).
Personally, if I were preparing major-release notes, I don't think
I'd use a --master-only switch even if I had it. There aren't so many
back-branch commits that it's hard to get rid of them manually, and
having the full history in front of you makes it easier to be sure
you've deleted the matching HEAD commits too.
regards, tom lane
Tom Lane wrote: > I wrote: > > So I'd vote for having both --master-only and its inverse > > --ignore-master, but I'm not sure we need anything more general > > than that. > > On second thought ... one big problem with --master-only is that > it's useful only to the extent that you trust git_changelog to > have matched up master and back-branch commits. The tool is definitely > not perfect about that: sometimes related commits will not have > identical texts (this would be the committer's fault) or the timestamps > are not close enough (which can be git's fault, because of the way git > pull works). > > Personally, if I were preparing major-release notes, I don't think > I'd use a --master-only switch even if I had it. There aren't so many > back-branch commits that it's hard to get rid of them manually, and > having the full history in front of you makes it easier to be sure > you've deleted the matching HEAD commits too. It is true that you might get a master-only commit and not see the back-branch commits that went with it. Usually such commits are either well known or mention the fact in the commit message. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +