Re: Proposal: Document ABI Compatibility

On Jun 19, 2024, at 05:41, Peter Eisentraut <peter@eisentraut.org> wrote:

> This is probably a bit confusing.  This might as well mean client application code against libpq.  Better something
like"server plugin code that uses the PostgreSQL server APIs". 

That works.

> 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). 

>> PostgreSQL avoids unnecessary API changes in major releases, but usually ships a few necessary API changes,
includingdeprecation, renaming, and argument variation. 
>
> Obviously, as a practical matter, there won't be random pointless changes.  But I wouldn't go as far as writing
anythingdown about how these APIs are developed. 

Fair enough, was trying to give some idea of the sorts of changes. Don’t have to include them.

>> In such cases the incompatible changes will be listed in the Release Notes.
>
> I don't think anyone is signing up to do that.

It needn’t be comprehensive. Just mention that an ABI or API changed in the release note item. Unless they almost *all*
makesuch changes. 

>> Minor Releases
>> --------------

> I think one major problem besides actively avoiding or managing such minor-version ABI breaks is some automated
detection. Otherwise, this just means "we try, but who knows”. 

I think you *do* try, and the fact that there are so few issues means you succeed at that. I’m not advocating for an
ABIguarantee here, just a description of the policy committees already follow. 

Here’s an update based on all the feedback, framing things more from the perspective of “do I need to recompile this or
changemy code”. Many thanks! 

``` md
ABI Policy
==========

Changes to the the PostgreSQL server APIs may require recompilation of server plugin code that uses them. This policy
describesthe core team's approach to such changes, and what server API users can expect. 

Major Releases
--------------

Applications that use server APIs must be compiled for each major release supported by the application. The inclusion
of`PG_MODULE_MAGIC` ensures that code compiled for one major version will rejected by other major versions. Developers
needingto support multiple versions of PostgreSQL with incompatible APIs should use the `PG_VERSION_NUM` constant to
adjustcode as appropriate. For example: 

``` c
#if PG_VERSION_NUM >= 160000
#include "varatt.h"
#endif
```

The core team avoids unnecessary breakage, but users of the server APIs should expect and be prepared to make
adjustmentsand recompile for every major release. 

Minor Releases
--------------

PostgreSQL makes an effort to avoid server API and ABI breaks in minor releases. In general, an application compiled
againstany minor release will work with any other minor release, past or future. In the absence of automated detection
ofsuch changes, this is not a guarantee, but history such breaking changes have been extremely rare. 

When a change *is* required, PostgreSQL will choose the least invasive change possible, for example by squeezing a new
fieldinto padding space or appending it to the end of a struct. This sort of change should not impact dependent
applicationsunless they use `sizeof(the struct)` on a struct with an appended field, or create their own instances of
suchstructs --- patterns best avoided. 

In rare cases, however, even such non-invasive changes may be impractical or impossible. In such an event, the change
willbe documented in the Release Notes, and details on the issue will also be posted to [TBD; mail list? Blog post?
Newsitem?]. 

To minimize issues and catch changes early, the project strongly recommends that developers adopt continuous
integrationtesting at least for the latest minor release all major versions of Postgres they support. 
```


Best,

David