[gnome-devel-docs/wip/swilmet/prog-guidelines: 1/3] programming-guidelines: odd/even versions for stable/unstable releases

[Sébastien Wilmet <swilmet src gnome org>]

commit 9384624abb07f9a165891cb86ac431fd6910172f
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun Nov 8 17:12:51 2015 +0100

    programming-guidelines: odd/even versions for stable/unstable releases
    
    https://bugzilla.gnome.org/show_bug.cgi?id=757736

 programming-guidelines/C/versioning.page |   32 ++++++++++++++++++++++++++++-
 1 files changed, 30 insertions(+), 2 deletions(-)
---
diff --git a/programming-guidelines/C/versioning.page b/programming-guidelines/C/versioning.page
index f79cef6..f491499 100644
--- a/programming-guidelines/C/versioning.page
+++ b/programming-guidelines/C/versioning.page
@@ -49,6 +49,10 @@
         Libtool versions should be updated for API changes or additions.
         (<link xref="#libtool-versioning"/>)
       </p></item>
+      <item><p>
+        Even/odd <em>minor</em> package versions can be used respectively for
+        stable/unstable releases. (<link xref="#stable-unstable-versions"/>)
+      </p></item>
     </list>
   </synopsis>
 
@@ -140,6 +144,30 @@ AC_SUBST([LT_VERSION],[0:0:0])</code>
     <code>my_library_la_LDFLAGS = -version-info $(LT_VERSION)</code>
   </section>
 
+  <section id="stable-unstable-versions">
+    <title>Stable and Unstable Package Versions</title>
+
+    <p>
+      Most GNOME modules follow a convention for stable and unstable releases.
+      The minor version is even for stable releases and is odd for unstable
+      releases.  For example, the 3.20.* versions are stable, but the 3.19.*
+      versions are unstable.  The 3.19.* versions can be seen as alpha and beta
+      releases of the 3.20 version.
+    </p>
+
+    <p>
+      A new micro <em>stable</em> version (e.g. 3.20.0 → 3.20.1) doesn’t add
+      new features, only translation updates and bug fixes.  On the other hand,
+      <em>unstable</em> micro releases (e.g. 3.19.1 → 3.19.2) can add API, or
+      change or remove API which was added in a previous micro release in that
+      minor series.
+    </p>
+
+    <p>
+      The libtool version should be updated only for stable package versions.
+    </p>
+  </section>
+
   <section id="release-process">
     <title>Release Process</title>
 
@@ -172,8 +200,8 @@ AC_SUBST([LT_VERSION],[0:0:0])</code>
         Make sure you have no local changes: <cmd>git status</cmd>
       </p></item>
       <item><p>
-        Increment the libtool version number in <file>configure.ac</file> (if it
-        exists)
+        If the release is for a stable package version, increment the libtool
+        version number in <file>configure.ac</file> (if it exists)
       </p></item>
       <item><p>
         Add an entry to the <file>NEWS</file> file