Re: 9.5 release notes

On Thu, Jun 11, 2015 at 01:54:23PM +0900, Michael Paquier wrote:
> On Thu, Jun 11, 2015 at 1:15 PM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> > I have committed the first draft of the 9.5 release notes. You can view
> > the output here:
> >
> > http://momjian.us/pgsql_docs/release-9-5.html
> >
> > and it will eventually appear here:
> >
> > http://www.postgresql.org/docs/devel/static/release.html
> >
> > I am ready to make suggested adjustments, though I am traveling for
> > conferences for the next ten days so there might a delay in my replies.
>
> Here are some review comments:
> + <para>
> + RETURN WHERE
> + </para>
> What is that?

It says the OID is returned, but where? I don't see it in psql.

> + <para>
> + WHAT IS A STATISTICS SNAPSHOT?
> + </para>
> + </listitem>
> It defines the last time when the global statistics file of pgstat has
> been written. Perhaps documentation should be made clearer.

Update with this text:

This represents the last time the snapshot files was written to
the file system.

> + <para>
> + The remote snapshot must have been exported by
> + <function>pg_export_snapshot()</> or been defined as a
> + logical replication slot. This can be used by parallel
> + <application>pg_dump</> to use a consistent snapshot across
> + <application>pg_dump</> processes.
> + </para>
> Perhaps "or been defined when creating a logical replication slot
> through a replication connection".

Sure, updated paragraph:

The remote snapshot must have been exported by
<function>pg_export_snapshot()</> or been defined when creating
a logical replication slot. This can be used by parallel
<application>pg_dump</> to use a consistent snapshot across
<application>pg_dump</> processes.

> + <listitem>
> + <para>
> + Simplify <acronym>WAL</> record format (Heikki Linnakangas)
> + </para>
> +
> + <para>
> + This allows external tools to more easily process <acronym>WAL</>
> + files.
> + </para>
> + </listitem>
> More precision could be brought here. What the new format allows is
> actually to track more easily what are the blocks modified for
> relations, something possible without having the knowledge of the
> record type directly.

OK, new text:

This allows external tools to more easily track what blocks
are modified.

> + <para>
> + This is particularly helpful for warm standbys.
> + </para>
> "for warm standbys to control the timing at which WAL segment files
> are retrieved from a WAL archive."

That feels redundant to the major description of the item.

> I think that the following items should be added as well:
> - Improvement of file version information for Windows builds (Noah
> Misch, Michael Paquier), commit ee9569e. The file version information
> was missing for a set of contrib modules as well as a handful of
> libraries and binaries (like conversion_procs, zic, pg_regress, etc.).
> This item should mention that all the binaries and libraries produced
> by a Windows build now contain file version information. This could be
> merged as well with this item as both are related:
> + <para>
> + Add icons to all <productname>MSVC</>-built binaries (Noah Misch)
> + </para>

OK, merged into the existing item:

Add icons to all <productname>MSVC</>-built binaries and version
information to all <systemitem class="osname">MS Windows</>
binaries (Noah Misch)

> - Move pg_lzcompress and pg_lzdecompress to libpqcommon, commit
> 40bede54. This was some legwork for wal_compression but external
> binary tools can take advantage of using it now more freely. Those
> APIs have been reworked as well to be more generic, somewhat similarly
> to the interface lz4 exposes to the user.

Uh, do we actually want to document that API for users? I didn't think so.

> - Addition of palloc_extended (8c8a886) to give module developers a
> fallback plan instead of OOM ERROR that palloc throws mandatorily.
> MemoryContextAllocExtended() can be used on another memory context
> than the current one similarly (bd4e2fd9). Feel free to discard this
> one if this is not appropriate in the release notes.

Same question. I am happy to mention it, but if we mention it, we are
encouraging people to use it.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ Everyone has their own god. +