Re: Proposal: Document ABI Compatibility - Mailing list pgsql-hackers

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
forminor 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
codecompiled 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
codein 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
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?].
 

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