Re: Patch to git_changelog for release note creation

On Tue, Mar 15, 2011 at 10:25 AM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> Robert Haas wrote:
>> On Tue, Mar 15, 2011 at 9:59 AM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
>> > Bruce Momjian <bruce(at)momjian(dot)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