Re: 9.5 release notes - Mailing list pgsql-hackers

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@momjian.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
consistentsnapshot 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">MSWindows</>       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@momjian.us>        http://momjian.us EnterpriseDB
http://enterprisedb.com
 + Everyone has their own god. +