Patch to git_changelog for release note creation

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