Re: 7.4 compatibility question - Mailing list pgsql-hackers

On Wed, 2003-10-22 at 01:08, Bruce Momjian wrote:
> Do you think I include every user-visible change in the release notes?
> It would be 2-3x longer, and probably not more useful.

> Part of the reason the release notes are read is
> because they are _readable_

On the contrary, I think we could do a lot to make the release notes
more readable, while at the same time providing more information to
users.

We're really serving two different audiences with the release notes.
Some people are just interested in the highlights of the release, so
that they are up to date on the latest new PostgreSQL functionality. For
these people, I think the existing "highlights of the release" section
at the top of the release notes is sufficient, although it could
probably be made a less terse.

The second audience is the people who are really interested in exactly
what has changed between the new release of PostgreSQL and the previous
release series. It is important that we make it easy for an admin
planning a PostgreSQL upgrade at a fairly large site to be able to see
what changes in PostgreSQL have been made, and what changes will be
necessary in their own applications. This audience is served fairly well
by the present release notes, but I think we could do better. The
backward-incompatibility section could definitely be improved, and the
whole process of summarizing the CVS logs after the fact is sure to lose
information. Furthermore, many of the release note entries are so brief
that it's difficult, even for someone familiar with PostgreSQL, to tell
exactly what they mean. Sometimes the entry doesn't even bother to
specify exactly what has been changed. Using complete sentences, where
warranted, and describing complex or important changes with a full
paragraph of text would be a good idea, IMHO. I've appended a few
examples of less-than-optimal entries to this mail.

So I think we could make the release notes more useful if we provided a
bit more detail in each entry, and documented changes more extensively.
We could also make better use of SGML, for example by adding <xref>s to
the release notes where applicable. I think we also need to *really*
maintain the release notes incrementally during 7.5 development, rather
than having Bruce summarize the CVS logs at the end. IMHO, every patch
that makes a significant change should update the release notes, when
the patch is applied.

Anyway, those are my thoughts on how to improve the release notes. I've
been meaning to get this off my chest for a while, so thanks for the
chance :-)

Comments are welcome.

-Neil

Here are a few examples of less-than-optimal entries I noticed while
browsing the release notes recently:

This HISTORY entry from 7.4 doesn't really tell anyone anything:
       * Multiple pg_dump fixes, including tar format and large objects

Or take this entry -- I can basically decipher what it means, but it
takes a fair degree of difficulty:
    * Disallow literal carriage return as a data value,      backslash-carriage-return and \r are still allowed
(Bruce)

Or this entry, which once again conveys little useful information, to me
at least:
    * Improve \d display (Christopher)