Re: 7.4 compatibility question

Neil Conway wrote:
> 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.
>
>
> 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

I agree it would be nice to use more xrefs in the release notes.

What happens when you go into more detail is that it comes even more
confusing --- in most cases we fixed some obscure flag combination or
something, and explaining that is even harder than just saying we fixed
some rare pg_dump failure cases. The people who reported the problem
have already gotten their fix, and in most cases, they are the only ones
to have ever tried that combination --- documenting that doesn't really
add much, at least for me and I would assume 99% of our users. We could
go for 99.9% of our users, but that makes things harder to filter for
the other 99%.

Please do a test --- do a cvs log of the bin/pg_dump directory and see
if I missed anything significant in the release notes.

If you start listing obscure changes, the significant ones don't really
stand out anymore. You could add a 'obscure changes' section, but I
think once you create the list and read it, it will look pretty obscure.

> 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)

OK, please improve the wording.

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

There were a huge number of \d display improvements --- do \d in 7.4 and
you will see them --- I don't see much value in saying, "Rules now
display as ...", or "defaults now have more parens".

I have always encouraged people to improve the existing notes. I don't
pretend to use the perfect wording --- please send in improvements.

As far as incrementally updating the release notes --- lots of our work
is incremental, meaning we fix X, then add Y, and Z, and the resulting
change is one release note entry (psql \d display improvements, for
example). Documenting them separately just leads to a mess of entries
that we have to consolidate at the end anyway.

--
Bruce Momjian | http://candle.pha.pa.us
pgman(at)candle(dot)pha(dot)pa(dot)us | (610) 359-1001
+ If your life is a hard drive, | 13 Roberts Road
+ Christ can be your backup. | Newtown Square, Pennsylvania 19073