The new file docs/libcurl/ABI describes how we view ABI breakages, soname

bumps and what the version number's significance to all that is.

2 files changed, 52 insertions, 1 deletions

diff --git a/docs/libcurl/ABI b/docs/libcurl/ABI
new file mode 100644
index 000000000..06783b569
--- /dev/null
+++ b/docs/libcurl/ABI
@@ -0,0 +1,51 @@
+                                  _   _ ____  _
+                              ___| | | |  _ \| |
+                             / __| | | | |_) | |
+                            | (__| |_| |  _ <| |___
+                             \___|\___/|_| \_\_____|
+
+                          libcurl's binary interface
+
+ABI
+
+  First, allow me to define the word for this context: ABI describes the
+  low-level interface between an application program a library. Calling
+  conventions, function arguments, return values, struct sizes/defines and
+  more.
+
+Upgrades
+
+  In the vast majority of all cases, a typical libcurl upgrade does not break
+  the ABI at all. Your application can remain using libcurl just as before,
+  only with less bugs and possibly with added new features. You need to read
+  the release notes, and if they mention an ABI break/soname bump, you may
+  have to verify that your application still builds fine and uses libcurl as
+  it now is defined to work.
+
+Version Numbers
+
+  In libcurl land, you really can't tell by the libcurl version number if that
+  libcurl is binary compatible or not with another libcurl version.
+
+Soname Bumps
+
+  Whenever there are changes done to the library that will cause an ABI
+  breakage, that may require your application to get attention or possibly be
+  changed to adhere to new things, we will bump the soname. Then the library
+  will get a different output name and thus can in fact be installed in
+  parallell with an older installed lib (on most systems). Thus, old
+  applications built against the previous ABI version will remain working and
+  using the older lib, while newer applications build and use the newer one.
+
+  During the first seven years of libcurl releases, there have only been four
+  ABI breakages.
+
+Downgrades
+
+  Going to an older libcurl version from one you're currently using can be a
+  tricky thing. Mostly we add features and options to newer libcurls as that
+  won't break ABI or hamper existing applications. This has the implication
+  that going backwards may get you in a situation where you pick a libcurl
+  that doesn't support the options your application needs. Or possibly you
+  even downgrade so far so you cross an ABI break border and thus a different
+  soname, and then your application may need to adapt to the modified ABI.
diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am
index ea96cea1d..dbc04ce57 100644
--- a/docs/libcurl/Makefile.am
+++ b/docs/libcurl/Makefile.am
@@ -57,7 +57,7 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \
 
 CLEANFILES = $(HTMLPAGES) $(PDFPAGES)
 
-EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4
+EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 ABI
 
 MAN2HTML= roffit --mandir=. < $< >$@