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 [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup. | Newtown Square, Pennsylvania 19073 ---------------------------(end of broadcast)--------------------------- TIP 3: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly
