Re: Proposal: Document ABI Compatibility

On 24.06.24 22:26, David E. Wheeler wrote:
>> But now we're talking about API.  That might be subject of another document or another section in this one, but it
seemsconfusing to mix this with the ABI discussion.
 
> Hrm. They’re super closely-related in my mind, as an extension developer. I need to know both! I guess I’m taking of
thispolicy as what I can expect may be changed (and how to adapt to it) and what won’t.
 
> 
> That said, I’m fine to remove the API stuff if there’s consensus objecting to it, to be defined in a separate policy
(perhapson the same doc page).
 

I took at a stab at this, using some of your text, but discussing API 
and ABI separately.


# Server API and ABI guidance

This section contains guidance to authors of extensions and other
server plugins about ABI and API stability in the PostgreSQL server.

## General

The PostgreSQL server contains several well-delimited APIs for server
plugins, such as the function manager (fmgr), SPI, and various hooks
specifically designed for extensions.  These interfaces are carefully
managed for long-term stability and compatibility.  However, the
entire set of global functions and variables in the server effectively
constitutes the publicly usable API, but most parts of that were not
designed with extensibility and long-term stability in mind.  That
means, while taking advantage of these interfaces is valid, the
further one strays from the well-trodden path, the likelier it will be
that one might encounter ABI or API compatibility issues at some
point.  Extension authors are also encouraged to provide feedback
about their requirements, so that over time, as new use patterns
arise, certain interfaces can be consider more stabilized or new
better-designed interfaces for new uses can be added.

## API compatibility

(API = application programming interface, meaning the interface used
at compile time)

### Major versions

There is _no_ promise of API compatibility between PostgreSQL major
versions.  That means, extension code might require source code
changes to work with multiple major versions.  These can usually be
managed with preprocessor conditions like `#if PG_VERSION_NUM >=
160000`.  Sophisticated extensions that use interfaces beyond the
well-delimited ones usually require a few such changes for each major
server version.

### Minor versions

PostgreSQL makes an effort to avoid server API breaks in minor
releases.  In general, extension code that compiles and works with
some minor release should also compile and work with any other minor
release, past or future.

When a change *is* required, this will be carefully managed, taking
the requirements of extensions into account.  Such changes will be
communicated in the release notes.

## ABI compatibility

(ABI = application binary interface, meaning the interface used at run
time)

### Major versions

Servers of different major versions have intentionally incompatible
ABIs.  That means, extensions that use server APIs must be re-compiled
for each major release.  The inclusion of `PG_MODULE_MAGIC` ensures
that code compiled for one major version will be rejected by other
major versions.

### Minor versions

PostgreSQL makes an effort to avoid server ABI breaks in minor
releases.  In general, an extension compiled against any minor release
should work with any other minor release, past or future.

When a change *is* required, PostgreSQL will choose the least invasive
change possible, for example by squeezing a new field into padding
space or appending it to the end of a struct.  These sorts of changes
should not impact extensions unless they use very unusual code
patterns.

In rare cases, however, even such non-invasive changes may be
impractical or impossible.  In such an event, the change will be
carefully managed, taking the requirements of extensions into account.
Such changes will also be documented in the release notes.

Note, however, again that many parts of the server are not designed or
maintained as publicly-consumable APIs (and that, in most cases, the
actual boundary is also not well-defined).  If urgent needs arise,
changes in those parts will naturally be done with less consideration
for extension code than changes in well-defined and widely used
interfaces.

Also, in the absence of automated detection of such changes, this is
not a guarantee, but historically such breaking changes have been
extremely rare.