SDL: Switch versioning scheme to be the same as GLib and Flatpak

From cd7c2f1de7d9e418bb554047d714dd7cacc020ff Mon Sep 17 00:00:00 2001
From: Simon McVittie <[EMAIL REDACTED]>
Date: Tue, 3 May 2022 15:16:11 +0100
Subject: [PATCH] Switch versioning scheme to be the same as GLib and Flatpak

For stable releases, this gives us the ability to make bugfix-only point
releases such as 2.24.1 if we want to, and distinguish between them
programmatically. For example, this ability could have been useful after
2.0.16 to fix Xwayland regressions, and after 2.0.18 to fix event loop
regressions.

For development releases, this gives us the ability to make multiple
prereleases during the same feature cycle, and distinguish between them
programmatically. For example, this would have been useful during 2.0.22
development, which went through three prereleases before reaching the
final release.

Signed-off-by: Simon McVittie <smcv@collabora.com>
---
 CMakeLists.txt                 | 12 ++++---
 Makefile.os2                   |  4 +--
 WhatsNew.txt                   | 14 +++++++-
 Xcode/SDL/Info-Framework.plist |  4 +--
 build-scripts/winrtbuild.ps1   |  2 +-
 configure.ac                   | 11 ++++---
 docs/release_checklist.md      | 58 +++++++++++++++++++++++++++++-----
 include/SDL_version.h          |  4 +--
 src/main/windows/version.rc    |  8 ++---
 9 files changed, 89 insertions(+), 28 deletions(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 5327874e7c1..718d38f21e8 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -58,8 +58,8 @@ include(${SDL2_SOURCE_DIR}/cmake/sdlchecks.cmake)
 
 # See docs/release_checklist.md
 set(SDL_MAJOR_VERSION 2)
-set(SDL_MINOR_VERSION 0)
-set(SDL_MICRO_VERSION 23)
+set(SDL_MINOR_VERSION 23)
+set(SDL_MICRO_VERSION 0)
 set(SDL_INTERFACE_AGE 0)
 set(SDL_BINARY_AGE 23)
 set(SDL_VERSION "${SDL_MAJOR_VERSION}.${SDL_MINOR_VERSION}.${SDL_MICRO_VERSION}")
@@ -74,11 +74,15 @@ set(SDL_CMAKE_DEBUG_POSTFIX "d"
 mark_as_advanced(CMAKE_IMPORT_LIBRARY_SUFFIX SDL_CMAKE_DEBUG_POSTFIX)
 
 # Calculate a libtool-like version number
-math(EXPR LT_CURRENT "${SDL_MICRO_VERSION} - ${SDL_INTERFACE_AGE}")
+math(EXPR LT_CURRENT "${SDL_MINOR_VERSION} - ${SDL_INTERFACE_AGE}")
 math(EXPR LT_AGE "${SDL_BINARY_AGE} - ${SDL_INTERFACE_AGE}")
 math(EXPR LT_MAJOR "${LT_CURRENT}- ${LT_AGE}")
 set(LT_REVISION "${SDL_INTERFACE_AGE}")
-set(LT_RELEASE "${SDL_MAJOR_VERSION}.${SDL_MINOR_VERSION}")
+# For historical reasons, the library name redundantly includes the major
+# version twice: libSDL2-2.0.so.0.
+# TODO: in SDL 3, set the OUTPUT_NAME to plain SDL3, which will simplify
+# it to libSDL3.so.0
+set(LT_RELEASE "2.0")
 set(LT_VERSION "${LT_MAJOR}.${LT_AGE}.${LT_REVISION}")
 
 #message(STATUS "${LT_VERSION} :: ${LT_AGE} :: ${LT_REVISION} :: ${LT_CURRENT} :: ${LT_RELEASE}")
diff --git a/Makefile.os2 b/Makefile.os2
index 53e7421418d..89985e67cfa 100644
--- a/Makefile.os2
+++ b/Makefile.os2
@@ -12,8 +12,8 @@
 
 LIBNAME = SDL2
 MAJOR_VERSION = 2
-MINOR_VERSION = 0
-MICRO_VERSION = 23
+MINOR_VERSION = 23
+MICRO_VERSION = 0
 VERSION = $(MAJOR_VERSION).$(MINOR_VERSION).$(MICRO_VERSION)
 DESCRIPTION = Simple DirectMedia Layer 2
 
diff --git a/WhatsNew.txt b/WhatsNew.txt
index 727ccc60b73..401b0a7545f 100644
--- a/WhatsNew.txt
+++ b/WhatsNew.txt
@@ -2,10 +2,22 @@
 This is a list of major changes in SDL's version history.
 
 ---------------------------------------------------------------------------
-2.0.24:
+2.24.0:
 ---------------------------------------------------------------------------
 
 General:
+* New version numbering scheme, similar to GLib and Flatpak.
+    * An even number in the minor version (second component) indicates
+      a production-ready stable release such as 2.24.0, which would have
+      been 2.0.24 under the old system.
+      * The patchlevel (micro version, third component) indicates a
+        bugfix-only update: for example, 2.24.1 would be a bugfix-only
+        release to fix bugs in 2.24.0, without adding new features.
+    * An odd number in the minor version indicates a prerelease such
+      as 2.23.0. Stable distributions should not use these prereleases.
+      * The patchlevel indicates successive prereleases, for example
+        2.23.1 and 2.23.2 would be prereleases during development of
+        the SDL 2.24.0 stable release.
 * Added SDL_bsearch() to the stdlib routines
 * Added functions to get the platform dependent name for a joystick or game controller:
     * SDL_JoystickPathForIndex()
diff --git a/Xcode/SDL/Info-Framework.plist b/Xcode/SDL/Info-Framework.plist
index 76626f66bb9..bb7986b873f 100644
--- a/Xcode/SDL/Info-Framework.plist
+++ b/Xcode/SDL/Info-Framework.plist
@@ -19,10 +19,10 @@
 	<key>CFBundlePackageType</key>
 	<string>FMWK</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2.0.23</string>
+	<string>2.23.0</string>
 	<key>CFBundleSignature</key>
 	<string>SDLX</string>
 	<key>CFBundleVersion</key>
-	<string>2.0.23</string>
+	<string>2.23.0</string>
 </dict>
 </plist>
diff --git a/build-scripts/winrtbuild.ps1 b/build-scripts/winrtbuild.ps1
index 1e0ac7a0b24..ab835815bb2 100644
--- a/build-scripts/winrtbuild.ps1
+++ b/build-scripts/winrtbuild.ps1
@@ -39,7 +39,7 @@
 #
 
 # Base version of SDL, used for packaging purposes
-$SDLVersion = "2.0.23"
+$SDLVersion = "2.23.0"
 
 # Gets the .bat file that sets up an MSBuild environment, given one of
 # Visual Studio's, "PlatformToolset"s.
diff --git a/configure.ac b/configure.ac
index bddb621f5bd..27c931660be 100644
--- a/configure.ac
+++ b/configure.ac
@@ -12,8 +12,8 @@ orig_CFLAGS="$CFLAGS"
 dnl Set various version strings - taken gratefully from the GTk sources
 # See docs/release_checklist.md
 SDL_MAJOR_VERSION=2
-SDL_MINOR_VERSION=0
-SDL_MICRO_VERSION=23
+SDL_MINOR_VERSION=23
+SDL_MICRO_VERSION=0
 SDL_INTERFACE_AGE=0
 SDL_BINARY_AGE=23
 SDL_VERSION=$SDL_MAJOR_VERSION.$SDL_MINOR_VERSION.$SDL_MICRO_VERSION
@@ -29,8 +29,11 @@ AC_SUBST(SDL_VERSION)
 LT_INIT([win32-dll])
 LT_LANG([Windows Resource])
 
-LT_RELEASE=$SDL_MAJOR_VERSION.$SDL_MINOR_VERSION
-LT_CURRENT=`expr $SDL_MICRO_VERSION - $SDL_INTERFACE_AGE`
+# For historical reasons, the library name redundantly includes the major
+# version twice: libSDL2-2.0.so.0.
+# TODO: in SDL 3, stop using -release, which will simplify it to libSDL3.so.0
+LT_RELEASE=2.0
+LT_CURRENT=`expr $SDL_MINOR_VERSION - $SDL_INTERFACE_AGE`
 LT_REVISION=$SDL_INTERFACE_AGE
 LT_AGE=`expr $SDL_BINARY_AGE - $SDL_INTERFACE_AGE`
 m4_pattern_allow([^LT_])
diff --git a/docs/release_checklist.md b/docs/release_checklist.md
index 4fec36d1497..2d4c5f9117f 100644
--- a/docs/release_checklist.md
+++ b/docs/release_checklist.md
@@ -1,8 +1,10 @@
 # Release checklist
 
+## New feature release
+
 * Update `WhatsNew.txt`
 
-* Bump version number to 2.0.EVEN for stable release
+* Bump version number to 2.EVEN.0 in all these locations:
 
     * `configure.ac`, `CMakeLists.txt`: `SDL_*_VERSION`
     * `Xcode/SDL/Info-Framework.plist`: `CFBundleShortVersionString`,
@@ -16,16 +18,14 @@
 * Bump ABI version information
 
     * `configure.ac`: `CMakeLists.txt`: `SDL_INTERFACE_AGE`, `SDL_BINARY_AGE`
-        * `SDL_INTERFACE_AGE += 1`
         * `SDL_BINARY_AGE += 1`
-        * if any functions have been added, set `SDL_INTERFACE_AGE` to 0
+        * set `SDL_INTERFACE_AGE` to 0
         * if backwards compatibility has been broken,
             set both `SDL_BINARY_AGE` and `SDL_INTERFACE_AGE` to 0
     * `Xcode/SDL/SDL.xcodeproj/project.pbxproj`: `DYLIB_CURRENT_VERSION`,
         `DYLIB_COMPATIBILITY_VERSION`
-        * increment second number in `DYLIB_CURRENT_VERSION`
-        * if any functions have been added, increment first number in
-            `DYLIB_CURRENT_VERSION` and set second number to 0
+        * increment first number in `DYLIB_CURRENT_VERSION`
+        * set second number in `DYLIB_CURRENT_VERSION` to 0
         * if backwards compatibility has been broken,
             increase `DYLIB_COMPATIBILITY_VERSION` (?)
 
@@ -33,11 +33,53 @@
 
 * Do the release
 
-* Bump version number to 2.0.ODD for next development version
+## New bugfix release
+
+* Check that no new API/ABI was added
+
+    * If it was, do a new feature release (see above) instead
+
+* Bump version number from 2.Y.Z to 2.Y.(Z+1) (Y is even)
+
+    * Same places as listed above
+
+* Bump ABI version information
+
+    * `configure.ac`: `CMakeLists.txt`: `SDL_INTERFACE_AGE`, `SDL_BINARY_AGE`
+        * `SDL_INTERFACE_AGE += 1`
+        * `SDL_BINARY_AGE += 1`
+    * `Xcode/SDL/SDL.xcodeproj/project.pbxproj`: `DYLIB_CURRENT_VERSION`,
+        `DYLIB_COMPATIBILITY_VERSION`
+        * increment second number in `DYLIB_CURRENT_VERSION`
+
+* Regenerate `configure`
+
+* Do the release
+
+## After a feature release
+
+* Create a branch like `release-2.24.x`
+
+* Bump version number to 2.ODD.0 for next development branch
+
+    * Same places as listed above
+
+* Bump ABI version information
+
+    * Same places as listed above
+    * Assume that the next feature release will contain new API/ABI
+
+## New development prerelease
+
+* Bump version number from 2.Y.Z to 2.Y.(Z+1) (Y is odd)
 
     * Same places as listed above
 
 * Bump ABI version information
 
     * Same places as listed above
-        * initially assume that there is no new ABI
+    * Assume that the next feature release will contain new API/ABI
+
+* Regenerate `configure`
+
+* Do the release
diff --git a/include/SDL_version.h b/include/SDL_version.h
index c42b93b8927..302e4628d7e 100644
--- a/include/SDL_version.h
+++ b/include/SDL_version.h
@@ -58,8 +58,8 @@ typedef struct SDL_version
 /* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
 */
 #define SDL_MAJOR_VERSION   2
-#define SDL_MINOR_VERSION   0
-#define SDL_PATCHLEVEL      23
+#define SDL_MINOR_VERSION   23
+#define SDL_PATCHLEVEL      0
 
 /**
  * Macro to determine SDL version program was compiled against.
diff --git a/src/main/windows/version.rc b/src/main/windows/version.rc
index 25cd68a0efe..66ab6204ee1 100644
--- a/src/main/windows/version.rc
+++ b/src/main/windows/version.rc
@@ -9,8 +9,8 @@ LANGUAGE LANG_ENGLISH, SUBLANG_ENGLISH_US
 //
 
 VS_VERSION_INFO VERSIONINFO
- FILEVERSION 2,0,23,0
- PRODUCTVERSION 2,0,23,0
+ FILEVERSION 2,23,0,0
+ PRODUCTVERSION 2,23,0,0
  FILEFLAGSMASK 0x3fL
  FILEFLAGS 0x0L
  FILEOS 0x40004L
@@ -23,12 +23,12 @@ BEGIN
         BEGIN
             VALUE "CompanyName", "\0"
             VALUE "FileDescription", "SDL\0"
-            VALUE "FileVersion", "2, 0, 23, 0\0"
+            VALUE "FileVersion", "2, 23, 0, 0\0"
             VALUE "InternalName", "SDL\0"
             VALUE "LegalCopyright", "Copyright (C) 2022 Sam Lantinga\0"
             VALUE "OriginalFilename", "SDL2.dll\0"
             VALUE "ProductName", "Simple DirectMedia Layer\0"
-            VALUE "ProductVersion", "2, 0, 23, 0\0"
+            VALUE "ProductVersion", "2, 23, 0, 0\0"
         END
     END
     BLOCK "VarFileInfo"