[gimp] devel-docs: Add libtool-instructions.txt

[Mukund Sivaraman <muks src gnome org>]

commit 7bfc60462e6c91a73061943182d4612883e5ea82
Author: Mukund Sivaraman <muks banu com>
Date:   Wed Aug 27 08:39:42 2014 +0530

    devel-docs: Add libtool-instructions.txt

 configure.ac                        |    7 +++-
 devel-docs/Makefile.am              |    1 +
 devel-docs/libtool-instructions.txt |   65 +++++++++++++++++++++++++++++++++++
 3 files changed, 71 insertions(+), 2 deletions(-)
---
diff --git a/configure.ac b/configure.ac
index 5bf65fb..98bdef2 100644
--- a/configure.ac
+++ b/configure.ac
@@ -3,8 +3,11 @@
 AC_PREREQ(2.54)
 
 # Making releases on the stable branch:
-#   GIMP_MICRO_VERSION += 1;
-#   GIMP_INTERFACE_AGE += 1;
+#   gimp_micro_version += 1;
+#   gimp_interface_age += 1;
+#
+# For a description of libtool version variables, see:
+# devel-docs/libtool-instructions.txt
 
 m4_define([gimp_major_version], [2])
 m4_define([gimp_minor_version], [9])
diff --git a/devel-docs/Makefile.am b/devel-docs/Makefile.am
index c977d03..6d9adeb 100644
--- a/devel-docs/Makefile.am
+++ b/devel-docs/Makefile.am
@@ -28,6 +28,7 @@ EXTRA_DIST = \
        gih.txt                         \
        gpb.txt                         \
        includes.txt                    \
+       libtool-instructions.txt        \
        parasites.txt                   \
        pat.txt                         \
        gegl-porting-plan.txt           \
diff --git a/devel-docs/libtool-instructions.txt b/devel-docs/libtool-instructions.txt
new file mode 100644
index 0000000..1040a12
--- /dev/null
+++ b/devel-docs/libtool-instructions.txt
@@ -0,0 +1,65 @@
+configure.ac libtool settings
+=============================
+
+This is a brief description of how the various version variables at the
+top of configure.ac are to be set, including gimp_interface_age and
+gimp_binary_age.
+
+See the arithmetic under the "libtool versioning" comment heading in
+configure.ac as a reference.
+
+See https://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html
+for definitions of libtool "current", "revision" and "age" numbers as
+used below.
+
+When making a release
+---------------------
+
+(1) When making releases on the stable branch, set:
+  gimp_micro_version += 1;
+  gimp_interface_age += 1;
+
+  If gimp_binary_age is defined as a constant, set gimp_binary_age += 1;
+  else if gimp_binary_age is defined as an m4_eval(), leave it as it is.
+
+  The default gimp_binary_age m4_eval() expression auto-increments
+  itself.
+
+(2) NEVER increment gimp_interface_age and gimp_binary_age by more than
+1 at any time for whatever reason, or you will have to wear a brown
+paper bag on your head to hide your face for the rest of your life. If
+you increment gimp_interface_age by more than 1, then the libtool
+"current" number is decremented which could result in incompatible
+library interface with existing bin programs.
+
+(3) If any functions have been added, set gimp_interface_age=0. This
+will cause the "current" and "age" part of libtool version to bump
+upwards, increasing the interface number the library implements while
+keeping the minimum interface number supported the same as before
+(i.e., backwards compatible ABI).
+
+  Example: In GIMP 2.8.10, with gimp_minor_version=8,
+  gimp_micro_version=10 and gimp_interface_age=10 (incremented by 1
+  for every micro release), current=800 and age=800, which means that
+  the libraries support interface numbers 0 through 800, and the
+  interface DID NOT change at all between GIMP 2.8.0 to GIMP 2.8.10.
+
+  Example: In GIMP 2.8.12, with gimp_minor_version=8,
+  gimp_micro_version=12 and gimp_interface_age=0, current=812 and
+  age=812, which means that the libraries support interface numbers 0
+  through 812, and the ABI interface DID change in backwards
+  compatible manner at the time gimp_interface_age was set to 0.
+
+(4) If backwards compatibility was broken, set gimp_binary_age=0 and
+gimp_interface_age=0. This will cause "age" part of libtool version to
+be 0, increasing the minimum interface supported to "current" part of
+libtool version, and making ABI backwards incompatible (the linker
+will not be able to use these libraries with programs compiled to work
+against older libraries.
+
+  Example: In GIMP 2.8.14, with gimp_minor_version=8,
+  gimp_micro_version=14, gimp_binary_age=0 and gimp_interface_age=0,
+  current=814 and age=0, which means that the libraries support
+  interface number 814 only, which tells libtool the ABI interface
+  changed in backwards incompatible manner at the time
+  gimp_binary_age was set to 0.