Re: Proposal: Document ABI Compatibility

On 18.06.24 00:37, David E. Wheeler wrote:
> 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

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

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

ok so far

> 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
> ```

But now we're talking about API. That might be subject of another
document or another section in this one, but it seems confusing to mix
this with the ABI discussion.

> PostgreSQL avoids unnecessary API changes in major releases, but usually ships a few necessary API changes, including deprecation, 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 anything down about how
these APIs are developed.

> In such cases the incompatible changes will be listed in the Release Notes.

I don't think anyone is signing up to do that.

> 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?].

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