Proposal: Document ABI Compatibility

Hackers,

At the PGConf Unconference session on improving extension support in core, we talked quite a bit about the recent anxiety among extension developers about a lack of an ABI compatibility guarantee in Postgres. Yurii Rashkovskii did a little header file spelunking and talked[1] about a few changes in minor version releases, including to apparent field order in structs. Jeremy Schneider posted the example on Twitter[2], and Peter G replied[3]:

> You must be referring to my commit 714780dc. The new field is stored within alignment padding (though only on back branches). Has this been tied to a known problem?

At the Unconference, Tom Lane said that this approach is pretty well drilled into the heads of every committer, and new ones pick it up through experience. The goal, IIUC, is to never introduce binary incompatibilities into the C APIs in minor releases. This standard would be good to document, to let extension developers know exactly what the guarantees are.

I’m happy to start a doc patch to add an ABI compatibility guarantee (presumably in xfunc.sgml), but want to be sure the details are right, namely:

* There are no source or binary compatibility guarantees for major releases.

* The ABI is guaranteed to change only in backward compatible ways in minor releases. If for some reason it doesn’t it’s a bug that will need to be fixed.

This ensures that an extension compiled against an earlier minor release will continue to work without recompilation on later minor releases of the same major version.

But if I understand correctly, the use of techniques like adding a new field in padding does not mean that extensions compiled on later minor releases will work on earlier minor releases of the same major version. Unless, that is, we can provide a complete list of things not to do (like make use of padding) to avoid it. Is that feasible?

Are there other details it should include?

Thanks,

David

[1]: https://www.pgevents.ca/events/pgconfdev2024/schedule/session/14
[2]: https://x.com/jer_s/status/1785717368804815026
[3]: https://x.com/petervgeoghegan/status/1785720228237717627