Thread: pgsql: First pass over release documentation.
Log Message:
-----------
First pass over release documentation. I trimmed down some of the
entries and removed a few.
Modified Files:
--------------
pgsql/doc/src/sgml:
release.sgml (r1.520 -> r1.521)
(http://developer.postgresql.org/cvsweb.cgi/pgsql/doc/src/sgml/release.sgml?r1=1.520&r2=1.521)
On Thu, 2007-10-18 at 05:15 +0000, Bruce Momjian wrote:
> First pass over release documentation. I trimmed down some of the
> entries and removed a few.
Much of the information you've removed is useful, IMHO. For example:
@@ -134,26 +119,12 @@ do it for earlier branch release files.
<para>
User-defined types can now have type modifiers
</para>
-
- <para>
- This allows a user type to take a modifier when
- being referenced, e.g. <type>SSNUM(7)</>. Previously only
- predefined system data types would allow this, e.g.
- <type>CHAR(4)</>.
- </para>
</listitem>
<listitem>
<para>
Automatically invalidate cached function code when table
- definitions change
- </para>
-
- <para>
- Previously PL/PgSQL functions that referenced temporary tables
- would fail if the temporary table was dropped and recreated
- between function invocations, unless <literal>EXECUTE</> was
- used.
+ definitions change or statistics are updated
</para>
</listitem>
@@ -181,13 +148,6 @@ do it for earlier branch release files.
<para>
Multiple autovacuum worker processes, and other autovacuum improvements
</para>
-
- <para>
- This allows multiple vacuums to run concurrently, meaning
- vacuuming of a large table will not prevent smaller tables from
- being vacuumed at the same time. Autovacuum is now considered
- mature and thus enabled by default.
- </para>
</listitem>
@@ -217,18 +177,6 @@ do it for earlier branch release files.
Asynchronous commit option allows transactions to be committed
but on-disk changes to be delayed
</para>
-
- <para>
- This feature dramatically increases performance for data
- modification queries. The disadvantage is that because on-disk
- changes are delayed, if the operating system crashes before data
- is written to the disk, committed data will be lost. This is
- useful only for applications that can accept some data loss.
- Unlike <varname>fsync</varname>, asynchronous commit does not
- risk database corruption; the worst case is that after an
- operating system crash the last few reportedly-committed
- transactions will be missing.
- </para>
</listitem>
In other words, the changes to the "Overview" section are mostly regressions, IMHO.
BTW, I'm not sure why you're uppercasing the names of data types -- they
are lowercased in most of the rest of the SGML docs.
-Neil
The overview descriptions were moved down to the body of the release notes. As far as the uppercase of type names, I though most SQL code uppercased them. --------------------------------------------------------------------------- Neil Conway wrote: > On Thu, 2007-10-18 at 05:15 +0000, Bruce Momjian wrote: > > First pass over release documentation. I trimmed down some of the > > entries and removed a few. > > Much of the information you've removed is useful, IMHO. For example: > > @@ -134,26 +119,12 @@ do it for earlier branch release files. > <para> > User-defined types can now have type modifiers > </para> > - > - <para> > - This allows a user type to take a modifier when > - being referenced, e.g. <type>SSNUM(7)</>. Previously only > - predefined system data types would allow this, e.g. > - <type>CHAR(4)</>. > - </para> > </listitem> > > <listitem> > <para> > Automatically invalidate cached function code when table > - definitions change > - </para> > - > - <para> > - Previously PL/PgSQL functions that referenced temporary tables > - would fail if the temporary table was dropped and recreated > - between function invocations, unless <literal>EXECUTE</> was > - used. > + definitions change or statistics are updated > </para> > </listitem> > > @@ -181,13 +148,6 @@ do it for earlier branch release files. > <para> > Multiple autovacuum worker processes, and other autovacuum improvements > </para> > - > - <para> > - This allows multiple vacuums to run concurrently, meaning > - vacuuming of a large table will not prevent smaller tables from > - being vacuumed at the same time. Autovacuum is now considered > - mature and thus enabled by default. > - </para> > </listitem> > > @@ -217,18 +177,6 @@ do it for earlier branch release files. > Asynchronous commit option allows transactions to be committed > but on-disk changes to be delayed > </para> > - > - <para> > - This feature dramatically increases performance for data > - modification queries. The disadvantage is that because on-disk > - changes are delayed, if the operating system crashes before data > - is written to the disk, committed data will be lost. This is > - useful only for applications that can accept some data loss. > - Unlike <varname>fsync</varname>, asynchronous commit does not > - risk database corruption; the worst case is that after an > - operating system crash the last few reportedly-committed > - transactions will be missing. > - </para> > </listitem> > > In other words, the changes to the "Overview" section are mostly regressions, IMHO. > > BTW, I'm not sure why you're uppercasing the names of data types -- they > are lowercased in most of the rest of the SGML docs. > > -Neil > -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://postgres.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
On Thu, 2007-10-18 at 01:53 -0400, Bruce Momjian wrote: > The overview descriptions were moved down to the body of the release > notes. ... which makes the overview descriptions too vague to be very useful, in some cases. The "Migration to version 8.3" section is also NOT the place to be eliding details. You've also removed other useful details from the rest of the release notes -- although the fact that this was done as one giant commit means it is rather hard to review :-( > As far as the uppercase of type names, I though most SQL code > uppercased them. Perhaps, but I think we should be consistent with the convention used elsewhere in the SGML documentation. -Neil
Neil Conway wrote: > On Thu, 2007-10-18 at 01:53 -0400, Bruce Momjian wrote: > > The overview descriptions were moved down to the body of the release > > notes. > > ... which makes the overview descriptions too vague to be very useful, > in some cases. The "Migration to version 8.3" section is also NOT the > place to be eliding details. You've also removed other useful details > from the rest of the release notes -- although the fact that this was > done as one giant commit means it is rather hard to review :-( I have made the details match what we usually do for level of detail in the release notes. We can change that, of course, but have not had problems in the past. > > As far as the uppercase of type names, I though most SQL code > > uppercased them. > > Perhaps, but I think we should be consistent with the convention used > elsewhere in the SGML documentation. I guess. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://postgres.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
On Thu, 2007-10-18 at 02:06 -0400, Bruce Momjian wrote:
> I have made the details match what we usually do for level of detail in
> the release notes.
WRT the overview, I'm not sure what a user is supposed to make of an
overview bullet point like "Use pseudo-transaction ids in read-only
transactions". If we're going to mention this at all, we ought to
include enough information for it to be sensible -- or else phrase it in
less technical terms ("Improve performance of read-only transactions by
lazily assigning transaction IDs"). Similar comments apply to the "ORDER
BY ... LIMIT" optimization, async commit, distributed checkpoint I/O,
etc.
For the "Migration to 8.3" section, I think we definitely need a lot
more details than are presently there ("New C macros for handling
variable-length data values" is not exactly very useful, for example).
Beyond those two sections, I still think you've removed quite a lot of
useful information in the rest of the release notes.
-Neil
Neil Conway wrote:
> On Thu, 2007-10-18 at 02:06 -0400, Bruce Momjian wrote:
> > I have made the details match what we usually do for level of detail in
> > the release notes.
>
> WRT the overview, I'm not sure what a user is supposed to make of an
> overview bullet point like "Use pseudo-transaction ids in read-only
> transactions". If we're going to mention this at all, we ought to
> include enough information for it to be sensible -- or else phrase it in
> less technical terms ("Improve performance of read-only transactions by
> lazily assigning transaction IDs"). Similar comments apply to the "ORDER
> BY ... LIMIT" optimization, async commit, distributed checkpoint I/O,
> etc.
Agreed. I need to make it more targeted at the benefit, like "reduce
need for vacuuming caused by read-only transactions". You are looking
at only my first cut at edits.
> For the "Migration to 8.3" section, I think we definitely need a lot
> more details than are presently there ("New C macros for handling
> variable-length data values" is not exactly very useful, for example).
The detail is below.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://postgres.enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +