Would it be too much to ask for that everytime a significant
user-visible change is checked in, the release notes are updated right
there as though they are documentation (which they are)?  This immediately
leads to three significant advantages:

1. Users can keep track of developement.

   Until after the start of beta, no user really had any idea what this
   new release was going to be about.  Users that started projects before
   the release notes were in readable form were wasting their time, if
   they chose PostgreSQL at all.

2. Developers can keep track of development.

   The number of changes for 7.2 is really enough for five releases, but
   no one can be expected to keep track of that.  So in the future, when
   the list gets too long, we make a release. ;-)

3. The list accurately reflects the actual work.

   Having the list reconstructed by a single person from CVS logs months
   after the fact is just way too lossy.

-- 
Peter Eisentraut   peter_e@gmx.net


Fri, 8 Feb 2002 13:01:17 -0500 (EST)
Peter Eisentraut <peter_e@gmx.net>
Maintaining the list of release changes
Peter Eisentraut <peter_e@gmx.net> writes:
> Would it be too much to ask for that everytime a significant
> user-visible change is checked in, the release notes are updated right
> there as though they are documentation (which they are)?
>    Having the list reconstructed by a single person from CVS logs months
>    after the fact is just way too lossy.

I agree completely, and was about to make a similar proposal.  However,
I'm not entirely sure where "the release notes" actually are, nor which
is the master copy.  Also, I'd prefer not to have to deal with SGML
markup for them.

What I'd suggest is that we keep a plaintext file somewhere near the
top of the CVS tree (in doc/ perhaps) that developers append
release-notes items to as the work is completed.  At the end of each
development cycle, Bruce can prepare the "nice looking" notes from that
source and then reset the file to empty for the next cycle.

			regards, tom lane

Fri, 08 Feb 2002 13:29:26 -0500
Tom Lane <tgl@sss.pgh.pa.us>
Re: Maintaining the list of release changes 
Tom Lane writes:

> I agree completely, and was about to make a similar proposal.  However,
> I'm not entirely sure where "the release notes" actually are, nor which
> is the master copy.  Also, I'd prefer not to have to deal with SGML
> markup for them.

The release notes are in the file release.sgml.  You don't really have to
deal with any markup there.  Look at the source under sect2 "Changes"; you
only need to insert a line there.  (Well, not there.  A new section will
be created.)  Grouping this into useful categories and creating the
"highlights" at the top can be done later during the usual revising and
editing.

> What I'd suggest is that we keep a plaintext file somewhere near the
> top of the CVS tree (in doc/ perhaps) that developers append
> release-notes items to as the work is completed.  At the end of each
> development cycle, Bruce can prepare the "nice looking" notes from that
> source and then reset the file to empty for the next cycle.

This (and later CVS log based ideas) don't really address my point #1:
keeping users informed.  You might underestimate that.  Plenty of users
would really like to try out development snapshots for their new projects,
or see if they compile, verify new features early, or just to play around.
But that's a lot harder if they don't know what's in there.

Secondly, why do double work if you can just do it right the first time?

We've been doing an excellent job lately about keeping the documentation
current.  This is really the same corner, but it's even more fundamental:
If you know what changes have been made since the last release you can
easily check if those changes have made it into the documentation.  I'm
not suggesting that we become laxer about documentation updates because of
this, neither do I want strict "every patch must update the release notes"
policies.  Just keep in mind that at some point, when you update the
documentation (meaning you feel your feature is reasonably complete to the
point that you want to let it loose), add a line to the release notes to
let people know it's there.  That's it.

-- 
Peter Eisentraut   peter_e@gmx.net


Fri, 8 Feb 2002 18:09:24 -0500 (EST)
Peter Eisentraut <peter_e@gmx.net>
Re: Maintaining the list of release changes 
Peter Eisentraut <peter_e@gmx.net> writes:
> Tom Lane writes:
>> What I'd suggest is that we keep a plaintext file somewhere near the
>> top of the CVS tree (in doc/ perhaps) that developers append
>> release-notes items to as the work is completed.  At the end of each
>> development cycle, Bruce can prepare the "nice looking" notes from that
>> source and then reset the file to empty for the next cycle.

> This (and later CVS log based ideas) don't really address my point #1:
> keeping users informed.

That's a valid complaint against CVS-log-based notes, since most people
probably don't have or know how to use tools like cvs2cl.  I don't see
why it's an argument against my idea of a dedicated text file, though.
Such a file would be just as readily found as release.sgml, possibly
more so.

> Secondly, why do double work if you can just do it right the first time?

A fair point.

I am still concerned about the prospect of either release.sgml or
a dedicated file becoming commit bottlenecks because everyone is
constantly hitting them (and in approximately the same place, too).
However, we probably can't know how big an annoyance that will be
in practice unless we try it.

			regards, tom lane

Fri, 08 Feb 2002 18:16:46 -0500
Tom Lane <tgl@sss.pgh.pa.us>
Re: Maintaining the list of release changes 
Tom Lane writes:

> That's a valid complaint against CVS-log-based notes, since most people
> probably don't have or know how to use tools like cvs2cl.  I don't see
> why it's an argument against my idea of a dedicated text file, though.
> Such a file would be just as readily found as release.sgml, possibly
> more so.

Do you have a suggestion for a name and where to put the file.  Will it be
removed or cleared before releases?

> I am still concerned about the prospect of either release.sgml or
> a dedicated file becoming commit bottlenecks because everyone is
> constantly hitting them (and in approximately the same place, too).

There are lots of and big projects that use GNU-style ChangeLogs.
Theoretically, they would all hit at the same place, but in practice this
is never a problem.  When an outsider submits a patch he just puts the
changelog entry into a separate attachment or right into the message and
the committer puts it into the right place.

We can make this to work as well.  If someone comes along, "hey, I just
added a --foo option to pg_bar to do xyx", the patch committer simply adds
a line "added --foo option to pg_bar to do xyz" to the log.  All the
release note items are one-liners, so this can't be too big of a deal.

-- 
Peter Eisentraut   peter_e@gmx.net


Mon, 11 Feb 2002 23:38:02 -0500 (EST)
Peter Eisentraut <peter_e@gmx.net>
Re: Maintaining the list of release changes 
Peter Eisentraut <peter_e@gmx.net> writes:
>> Such a file would be just as readily found as release.sgml, possibly
>> more so.

> Do you have a suggestion for a name and where to put the file.  Will it be
> removed or cleared before releases?

I think it should live in .../doc, same as TODO.  Not picky about name.

I don't think we should remove the file; removing and re-adding it will
probably do strange things to CVS history.  One could argue about
whether we even need to clear it.  Might be best to ship it as-is in
the release, and then clear it *after* the next version branch.

			regards, tom lane

Tue, 12 Feb 2002 16:29:01 -0500
Tom Lane <tgl@sss.pgh.pa.us>
Re: Maintaining the list of release changes 
Tom Lane writes:

> I think it should live in .../doc, same as TODO.  Not picky about name.
>
> I don't think we should remove the file; removing and re-adding it will
> probably do strange things to CVS history.  One could argue about
> whether we even need to clear it.  Might be best to ship it as-is in
> the release, and then clear it *after* the next version branch.

It seems that I'm going to have a hard time convincing people to put the
notes into the DocBook sources right away, so in order to get this
jump-started, I'll go with the text file.

New changes go at the top.  I guess we'll want to keep the one-liner,
barely-a-sentence format for now.

Not sure if we want to ship this file, but we can think about that later
when we see how it develops.

As for name, maybe CHANGES.  You could think of it this way:  Some changes
may cancel each other out along the way and may not go down into
"history".

-- 
Peter Eisentraut   peter_e@gmx.net


Fri, 15 Feb 2002 16:50:44 -0500 (EST)
Peter Eisentraut <peter_e@gmx.net>
Re: Maintaining the list of release changes 
Peter Eisentraut <peter_e@gmx.net> writes:
> As for name, maybe CHANGES.  You could think of it this way:  Some changes
> may cancel each other out along the way and may not go down into
> "history".

Sure.  Or maybe RECENTCHANGES, to point out that it's not a changelist
back to the beginning of time.  But I don't care much.  Please create
it, and I'll start making entries...

			regards, tom lane

Fri, 15 Feb 2002 17:56:43 -0500
Tom Lane <tgl@sss.pgh.pa.us>
Re: Maintaining the list of release changes 
...
> It seems that I'm going to have a hard time convincing people to put the
> notes into the DocBook sources right away, so in order to get this
> jump-started, I'll go with the text file.

Why would putting notes into the DocBook sources be a problem? It is as
trivial as it can get, and it would eliminate one of the few remaining
disconnects between presentable final documentation and folks doing the
work.

I'm happy having this in DocBook, Peter would prefer it too, and it
doesn't hurt or bite hard so why would it be a problem for others?

I'm afraid I purged some of this thread from my mail, but are there
issues other than "I don't know which file to use" or "I don't
understand DocBook markup"? Both of those are easy to fix...

                       - Thomas

Fri, 15 Feb 2002 16:30:07 -0800
Thomas Lockhart <lockhart@fourpalms.org>
Re: Maintaining the list of release changes