Re: First draft of PG 17 release notes

On Tue, Sep 10, 2024 at 08:28:42AM +0200, Jelte Fennema-Nio wrote:
> I think as an extension author there are usually three types of
> changes that are relevant:
> 1. New APIs/hooks that are meant for extension authors
> 2. Stuff that causes my existing code to not compile anymore
> 3. Stuff that changes behaviour of existing APIs code in a
> incompatible but silent way
> 
> For 1, I think adding them to the release notes makes total sense,
> especially if the new APIs are documented not only in source code, but
> also on the website. Nathan his change is of this type, so I agree
> with him it should be in the release notes.
> 
> For 2, I'll be able to easily find the PG commit that caused the
> compilation failure by grepping git history for the old API. So having
> these changes in the release notes seems unnecessary.
> 
> For 3, it would be very useful if it would be in the release notes,
> but I think in many cases it's hard to know what commits do this. So
> unless it's obviously going to break a bunch of extensions silently, I
> think we don't have to add such changes to the release notes.

So, we are looking at this commit:

    commit b5a9b18cd0b
    Author: Thomas Munro <tmunro@postgresql.org>
    Date:   Wed Apr 3 00:17:06 2024 +1300

    Provide API for streaming relation data.

    Introduce an abstraction allowing relation data to be accessed as a
    stream of buffers, with an implementation that is more efficient than
    the equivalent sequence of ReadBuffer() calls.

    Client code supplies a callback that can say which block number it wants
    next, and then consumes individual buffers one at a time from the
    stream.  This division puts read_stream.c in control of how far ahead it
    can see and allows it to read clusters of neighboring blocks with
    StartReadBuffers().  It also issues POSIX_FADV_WILLNEED advice ahead of
    time when random access is detected.

    Other variants of I/O stream will be proposed in future work (for
    example to support recovery, whose LsnReadQueue device in
    xlogprefetcher.c is a distant cousin of this code and should eventually
    be replaced by this), but this basic API is sufficient for many common
    executor usage patterns involving predictable access to a single fork of
    a single relation.

    Several patches using this API are proposed separately.

    This stream concept is loosely based on ideas from Andres Freund on how
    we should pave the way for later work on asynchronous I/O.

You are right that I do mention changes specifically designed for the
use of extensions, but there is no mention in the commit message of its
use for extensions.  In fact, I thought this was too low-level to be of
use for extensions.  However, if people feel it should be added, we have
enough time to add it.

I also mention changes that are _likely_ to affect extensions, but not
all changes that could affect extensions.  An interesting idea would be
to report all function signature changes in each major release in some
way.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  When a patient asks the doctor, "Am I going to die?", he means 
  "Am I going to die soon?"