Re: Proposal: Document ABI Compatibility

On 2024-06-11 10:55:38 -0400, 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.

I.e. for major versions it's "there is none"?

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

I don't think we actually exhaustively list all of them.

> Minor Releases
> --------------
>
> PostgreSQL makes every 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.

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

> 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)` or create their
> own instances of such structs --- patterns best avoided.

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.

Greetings,

Andres Freund