Re: Proposal: Document ABI Compatibility

On Jun 12, 2024, at 11:20, Andres Freund <andres@anarazel.de> wrote:

>> The PostgreSQL core team maintains two application binary interface (ABI) guarantees: one for major releases and one
forminor releases. 
>
> I.e. for major versions it's "there is none"?

Is it? ISTM that there is the intention not to break things that don’t need to be broken, though that doesn’t rule out
interfaceimprovements. 

>> In such cases the incompatible changes will be listed in the Release Notes.
>
> I don't think we actually exhaustively list all of them.

Should they be? I can maybe see the argument not to for major releases. But I’ve also has the experience of a new
failureon a major release and having to go find the reason for it and the fix, often requiring the attention of someone
ona mailing list who might rather tap the “compatibility changes” sign in the latest change log. :-) 

> s/every/a reasonable/ or just s/every/an/

✅

> The padding case doesn't affect sizeof() fwiw.

✅

> I think there's too often not an alternative to using sizeof(), potentially
> indirectly (via makeNode() or such. So this sounds a bit too general.

Is there some other way to avoid the issue? Or would constructor APIs need to be added to core?


Updated with your suggestions:


``` md

ABI Policy
==========

The PostgreSQL core team maintains two application binary interface (ABI) guarantees: one for major releases and one
forminor releases. 

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

Applications that use the PostgreSQL APIs must be compiled for each major release supported by the application. The
inclusionof `PG_MODULE_MAGIC` ensures that code compiled for one major version will rejected by other major versions. 

Furthermore, new releases may make API changes that require code changes. Use the `PG_VERSION_NUM` constant to adjust
codein a backwards compatible way: 

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

PostgreSQL avoids unnecessary API changes in major releases, but usually ships a few necessary API changes, including
deprecation,renaming, and argument variation. In such cases the incompatible changes will be listed in the Release
Notes.

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

PostgreSQL makes an effort to avoid both 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. 

When a change *is* required, PostgreSQL will choose the least invasive way 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?]. 

The project strongly recommends that developers adopt continuous integration testing at least for the latest minor
releaseall major versions of Postgres they support. 
```

Best,

David