Re: Proposal: Document ABI Compatibility

On Jun 12, 2024, at 11:20, Andres Freund <andres(at)anarazel(dot)de> wrote:

>> The PostgreSQL core team maintains two application binary interface (ABI) guarantees: one for major releases and one for minor 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 interface improvements.

>> 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 failure on a major release and having to go find the reason for it and the fix, often requiring the attention of someone on a 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 for minor releases.

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

Applications that use the PostgreSQL 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.

Furthermore, new releases may make API changes that require code changes. Use the `PG_VERSION_NUM` constant to adjust code in 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 against any 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 field into padding space or appending it to the end of a struct. This sort of change should not impact dependent applications unless, they use `sizeof(the struct)` on a struct with an appended field, or create their own instances of such structs --- patterns best avoided.

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

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

Best,

David