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

On Jun 10, 2024, at 15:39, Andres Freund <andres@anarazel.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
theircode, 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
anyguarantees 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
stufflike this can be surprising to extension maintainers with some expectation of minor release stability who had no
warningof the change. That kind of thing can dissuade some people from deciding to write or maintain extensions, and
leadothers 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
setexpectations? That’s where I want to start: can we publish a policy that reflects what committers already adhere to?
Andis there some way to let people know that an incompatible change is being released? Even if it just starts out in
therelease 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
thewording here! Let’s workshop this until it’s something the committers and core team can agree to. (At that point
I’llturn 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
forminor releases. 

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

Applications that use the PostgreSQL APIs must be compiled for each major release supported by the application. The
inclusionof `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
codein 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
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)` 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
willbe documented in the Release Notes, and details on the issue will also be posted to [TBD; mail list? Blog post?
Newsitem?]. 

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

Best,

David