Re: Proposal: Document ABI Compatibility

On Jun 10, 2024, at 15:39, Andres Freund <andres(at)anarazel(dot)de> wrote:

> That's 6 years ago, not sure we can really learn that much from that.
>
> And it's not like it's actually impossible, #ifdefs aren't great, but they are
> better than nothing.

Right, it’s just that extension authors could use some notification that such a change is coming so they can update their code, if necessary.

>> Or, to David C’s point, perhaps it would be better to say there are some categories of APIs that are not subject to any guarantees in minor releases?
>
> I'm honestly very dubious that this is a good point to introduce a bunch of
> formalism. It's a already a lot of work to maintain them, if we make it even
> harder we'll end up more fixes not being backported, because it's not worth
> the pain.

Well it’s a matter of distributing the work. I don’t want to increase anyone’s workload unnecessarily, but as it is stuff like this can be surprising to extension maintainers with some expectation of minor release stability who had no warning of the change. That kind of thing can dissuade some people from deciding to write or maintain extensions, and lead others to recompile and distribute binaries for every single minor release.

> To be blunt, the number of examples raised here doesn't seem to indicate that
> this is an area where we need to invest additional resources. We are already
> severely constrained as a project by committer bandwidth, there are plenty
> other things that seem more important to focus on.

So my question is, what’s the least onerous thing for committers to commit to doing that we can write down to properly set expectations? That’s where I want to start: can we publish a policy that reflects what committers already adhere to? And is there some way to let people know that an incompatible change is being released? Even if it just starts out in the release notes?

Based on this thread, I’ve drafted the sort of policy I have in mind. Please don’t assume I’m advocating for exactly the wording here! Let’s workshop this until it’s something the committers and core team can agree to. (At that point I’ll turn it into a doc patch) Have a look and let me know what you think.

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

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.

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