Add API and ABI stability guidance to the C language docs

Includes guidance for major and minor version releases, and sets
reasonable expectations for extension developers to follow.

Author: David Wheeler, Peter Eisentraut

Discussion: https://www.postgresql.org/message-id/flat/5DA9F9D2-B8B2-43DE-BD4D-53A4160F6E8D%40justatheory.com

diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 5b584a4f14446b4eb9ab5f537cb740a006940457..bf76490cbc010ddd9774defb44afa1548c068102 100644 (file)
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -2704,6 +2704,142 @@ CREATE FUNCTION concat_text(text, text) RETURNS text
 
 &dfunc;
 
+   
+    Server API and ABI Stability Guidance
+
+    
+     This section contains guidance to authors of extensions and other server
+     plugins about API and ABI stability in the
+     PostgreSQL server.
+    
+
+    
+     General
+
+     
+      The PostgreSQL server contains several
+      well-demarcated APIs for server plugins, such as the function manager
+      (fmgr, described in this chapter),
+      SPI (), and various hooks
+      specifically designed for extensions. These interfaces are carefully
+      managed for long-term stability and compatibility. However, the entire
+      set of global functions and variables in the server effectively
+      constitutes the publicly usable API, and most of it was not designed
+      with extensibility and long-term stability in mind.
+     
+
+     
+      Therefore, while taking advantage of these interfaces is valid, the
+      further one strays from the well-trodden path, the likelier it will be
+      that one might encounter API or ABI compatibility issues at some point.
+      Extension authors are encouraged to provide feedback about their
+      requirements, so that over time, as new use patterns arise, certain
+      interfaces can be considered more stabilized or new, better-designed
+      interfaces can be added.
+     
+    
+
+    
+     API Compatibility
+     
+      The API, or application programming interface, is the
+      interface used at compile time.
+     
+
+     
+      Major Versions
+      
+       There is no promise of API compatibility between
+       PostgreSQL major versions. Extension code
+       therefore might require source code changes to work with multiple major
+       versions. These can usually be managed with preprocessor conditions
+       such as #if PG_VERSION_NUM >= 160000.
+       Sophisticated extensions that use interfaces beyond the well-demarcated
+       ones usually require a few such changes for each major server version.
+      
+     
+
+     
+      Minor Versions
+      
+       PostgreSQL makes an effort to avoid server
+       API breaks in minor releases. In general, extension code that compiles
+       and works with a minor release should also compile and work with any
+       other minor release of the same major version, past or future.
+      
+
+      
+       When a change is required, it will be carefully
+       managed, taking the requirements of extensions into account. Such
+       changes will be communicated in the release notes (
+       linkend="release"/>).
+      
+     
+    
+
+    
+     ABI Compatibility
+      
+       The ABI, or application binary interface, is the
+       interface used at run time.
+      
+
+     
+      Major Versions
+      
+       Servers of different major versions have intentionally incompatible
+       ABIs. Extensions that use server APIs must therefore be re-compiled for
+       each major release. The inclusion of PG_MODULE_MAGIC
+       (see ) ensures that code compiled for
+       one major version will be rejected by other major versions.
+      
+     
+
+     
+      Minor Versions
+      
+       PostgreSQL makes an effort to avoid server
+       ABI breaks in minor releases. In general, an extension compiled against
+       any minor release should work with any other minor release of the same
+       major version, past or future.
+      
+
+      
+       When a change is required,
+       PostgreSQL will choose the least invasive
+       change possible, for example by squeezing a new field into padding
+       space or appending it to the end of a struct. These sorts of changes
+       should not impact extensions unless they use very unusual code
+       patterns.
+      
+
+      
+       In rare cases, however, even such non-invasive changes may be
+       impractical or impossible. In such an event, the change will be
+       carefully managed, taking the requirements of extensions into account.
+       Such changes will also be documented in the release notes (
+       linkend="release"/>).
+      
+
+      
+       Note, however, that many parts of the server are not designed or
+       maintained as publicly-consumable APIs (and that, in most cases, the
+       actual boundary is also not well-defined). If urgent needs arise,
+       changes in those parts will naturally be made with less consideration
+       for extension code than changes in well-defined and widely used
+       interfaces.
+      
+
+      
+       Also, in the absence of automated detection of such changes, this is
+       not a guarantee, but historically such breaking changes have been
+       extremely rare.
+      
+
+     
+    
+  
+
    
     Composite-Type Arguments