Subject: Re: PG 16 draft release notes ready

From: Bruce Momjian <[email-masked]>
Date: Thu, 18 May 2023 21:44:34 -0400

On Thu, May 18, 2023 at 04:12:26PM -0700, Peter Geoghegan wrote:
> On Thu, May 18, 2023 at 3:52 PM Bruce Momjian <[email-masked]> wrote:
> > So, I looked at this and the problem is that this is best as a single
> > release note entry because we are removing and adding, and if I moved it
> > to compatibility, I am concerned the new feature will be missed.  Since
> > WAL inspection is a utility operation, inn general, I think having it in
> > the pg_walinspect section makes the most sense.
> 
> I don't understand what you mean by that. The changes to
> *_till_end_of_wal() (the way that those duplicative functions were
> removed, and more permissive end_lsn behavior was added) is unrelated
> to all of the other changes. Plus it's just not very important.

I see what you mean now.  I have moved the function removal to the
incompatibilities section and kept the existing entry but remove the
text about the removed functions.

> > Okay, I went with:
> >
> >         Improve descriptions of pg_walinspect WAL record descriptions
> >         (Melanie Plageman, Peter Geoghegan)
> >
> > > Note also that the item "Add pg_waldump option --save-fullpage to dump
> > > full page images (David Christensen)" is tangentially related to
> > > pg_get_wal_block_info(), since you can also get FPIs using
> > > pg_get_wal_block_info() (in fact, that was originally its main
> > > purpose). I'm not saying that you necessarily need to connect them
> > > together in any way, but you might consider it.
> >
> > Well, there is so much _new_ in that tool that listing everything new
> > seems confusing.
> 
> There is pretty much one truly new piece of functionality added to
> pg_walinspect (the function called pg_get_wal_block_info was added) --
> since the enhancement to rmgr description output applies equally to
> pg_waldump, no matter where you place it in the release notes. So not
> sure what you mean.

I see what you mean now.  I have removed the mention of
pg_get_wal_block_info() and moved the three items back into the
extension section since there are only three pg_walinspect items now.

> > All changes committed.
> 
> Even after these changes, the release notes still refer to a function
> called "pg_get_wal_block". There is no such function, though -- not in
> Postgres 16, and not in any other major version.

Oh

> 
> As I said, there is a new function called "pg_get_wal_block_info". It
> should simply be presented as a whole new function that offers novel
> new functionality compared to what was available in Postgres 15 --
> without any further elaboration. (It happens to be true that
> pg_get_wal_block_info only reached its final form following multiple
> rounds of work in multiple commits, but that is of no consequence to
> users -- even the earliest form of the function appeared in a commit
> in the Postgres 16 cycle.)

Done.  Please see the URL for the updated text, diff attached.

-- 
  Bruce Momjian  <[email-masked]>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.
diff --git a/doc/src/sgml/release-16.sgml b/doc/src/sgml/release-16.sgml
index 47f6cae907..5c17237966 100644
--- a/doc/src/sgml/release-16.sgml
+++ b/doc/src/sgml/release-16.sgml
@@ -91,6 +91,17 @@ Processing such indexes is still possible using REINDEX SYSTEM.
 </para>
 </listitem>
 
+<!--
+Author: Michael Paquier <[email-masked]>
+2023-03-14 [5c1b66280] Rework design of functions in pg_walinspect
+-->
+
+<listitem>
+<para>
+Remove pg_walinspect functions pg_get_wal_records_info_till_end_of_wal() and pg_get_wal_stats_till_end_of_wal().
+</para>
+</listitem>
+
 <!--
 Author: Michael Paquier <[email-masked]>
 2023-03-17 [98ae2c84a] libpq: Remove code for SCM credential authentication
@@ -2848,6 +2859,55 @@ Previously constants appeared instead of placeholders, e.g., $1.
 </para>
 </listitem>
 
+<!--
+Author: Michael Paquier <[email-masked]>
+2023-01-23 [c31cf1c03] pg_walinspect: Add pg_get_wal_fpi_info()
+Author: Michael Paquier <[email-masked]>
+2023-03-10 [9ecb134a9] pg_walinspect: pg_get_wal_fpi_info() -> pg_get_wal_block
+Author: Peter Geoghegan <[email-masked]>
+2023-03-30 [122376f02] Show record information in pg_get_wal_block_info.
+Author: Peter Geoghegan <[email-masked]>
+2023-03-31 [df4f3ab51] Add show_data option to pg_get_wal_block_info.
+-->
+
+<listitem>
+<para>
+Add pg_walinspect function pg_get_wal_block_info() to report WAL block information (Michael Paquier, Melanie Plageman, Bharath Rupireddy)
+</para>
+</listitem>
+
+<!--
+Author: Michael Paquier <[email-masked]>
+2023-03-14 [5c1b66280] Rework design of functions in pg_walinspect
+-->
+
+<listitem>
+<para>
+Change how pg_walinspect functions pg_get_wal_records_info(), pg_get_wal_stats(), and pg_get_wal_block_info() interpret ending LSNs (Bharath Rupireddy)
+</para>
+
+<para>
+Previously ending LSNs which represent nonexistent WAL locations would generate an error, while they will now be interpreted as the end of the WAL.
+</para>
+</listitem>
+
+<!--
+Author: Peter Geoghegan <[email-masked]>
+2023-04-07 [7d8219a44] Show more detail in heapam rmgr descriptions.
+Author: Peter Geoghegan <[email-masked]>
+2023-04-07 [1c453cfd8] Show more detail in nbtree rmgr descriptions.
+Author: Peter Geoghegan <[email-masked]>
+2023-04-11 [96149a180] Fix Heap rmgr's desc output for infobits arrays.
+Author: Peter Geoghegan <[email-masked]>
+2023-04-19 [50547a3fa] Fix wal_consistency_checking enhanced desc output.
+-->
+
+<listitem>
+<para>
+Improve descriptions of pg_walinspect WAL record descriptions (Melanie Plageman, Peter Geoghegan)
+</para>
+</listitem>
+
 <!--
 Author: Tom Lane <[email-masked]>
 2023-01-02 [1fd3dd204] Add bt_multi_page_stats() function to contrib/pageinspec
@@ -2994,74 +3054,6 @@ Author: Andres Freund <[email-masked]>
 <para>
 Have postgres_fdw and dblink handle interrupts during connection establishment (Andres Freund)
 </para>
-</listitem>
-
-     </itemizedlist>
-
-    </sect4>
-
-    <sect4 id="release-16-walinspect">
-     <title><link linkend="pgwalinspect"><application>pg_walinspect</application></link></title>
-
-     <itemizedlist>
-
-<!--
-Author: Michael Paquier <[email-masked]>
-2023-01-23 [c31cf1c03] pg_walinspect: Add pg_get_wal_fpi_info()
-Author: Michael Paquier <[email-masked]>
-2023-03-10 [9ecb134a9] pg_walinspect: pg_get_wal_fpi_info() -> pg_get_wal_block
--->
-
-<listitem>
-<para>
-Add pg_walinspect function pg_get_wal_block() to report WAL block information (Michael Paquier, Melanie Plageman, Bharath Rupireddy)
-</para>
-</listitem>
-
-<!--
-Author: Peter Geoghegan <[email-masked]>
-2023-03-30 [122376f02] Show record information in pg_get_wal_block_info.
-Author: Peter Geoghegan <[email-masked]>
-2023-03-31 [df4f3ab51] Add show_data option to pg_get_wal_block_info.
--->
-
-<listitem>
-<para>
-Add output fields to pg_walinspect's function pg_get_wal_block_info() (Bharath Rupireddy, Peter Geoghegan)
-</para>
-</listitem>
-
-<!--
-Author: Michael Paquier <[email-masked]>
-2023-03-14 [5c1b66280] Rework design of functions in pg_walinspect
--->
-
-<listitem>
-<para>
-Change how pg_walinspect functions pg_get_wal_records_info(), pg_get_wal_stats(), and pg_get_wal_block_info() interpret ending LSNs (Bharath Rupireddy)
-</para>
-
-<para>
-Previously ending LSNs which represent nonexistent WAL locations would generate an error, while they will now be interpreted as the end of the WAL.  Functions pg_get_wal_records_info_till_end_of_wal() and
-pg_get_wal_stats_till_end_of_wal() have been removed.
-</para>
-</listitem>
-
-<!--
-Author: Peter Geoghegan <[email-masked]>
-2023-04-07 [7d8219a44] Show more detail in heapam rmgr descriptions.
-Author: Peter Geoghegan <[email-masked]>
-2023-04-07 [1c453cfd8] Show more detail in nbtree rmgr descriptions.
-Author: Peter Geoghegan <[email-masked]>
-2023-04-11 [96149a180] Fix Heap rmgr's desc output for infobits arrays.
-Author: Peter Geoghegan <[email-masked]>
-2023-04-19 [50547a3fa] Fix wal_consistency_checking enhanced desc output.
--->
-
-<listitem>
-<para>
-Improve descriptions of pg_walinspect WAL record descriptions (Melanie Plageman, Peter Geoghegan)
-</para>
 </listitem>
 
      </itemizedlist>

---

From: Peter Geoghegan <[email-masked]>
Date: Thu, 18 May 2023 19:15:26 -0700

> text about the removed functions.

Your patch now has two separate items for "[5c1b66280] Rework design
of functions in pg_walinspect", but even one item is arguably one too
many. The "ending LSN" item (the second item for this same commit)
should probably be removed altogether. If you're going to keep the
sentences that appear under that second item, then it should at least
be consolidated with the first item, in order that commit 5c1b66280
isn't listed twice.

Note also that the patch doesn't remove a remaining reference to an
update in how pg_get_wal_block_info() works, which (as I've said) is a
brand new function as far as users are concerned. Users don't need to
hear that it has been updated, since these release notes will also be
the first time they've been presented with any information about
pg_get_wal_block_info(). (This isn't very important; again, I suggest
that you avoid saying anything about any specific function, even if
you feel strongly that the "ending LSN" issue must be spelled out like
this.)

> extension section since there are only three pg_walinspect items now.

The wording for this item as it appears in the patch is: "Improve
descriptions of pg_walinspect WAL record descriptions". I suggest the
following wording be used instead: "Provide more detailed descriptions
of certain WAL records in the output of pg_walinspect and pg_waldump".

-- 
Peter Geoghegan