From 60d702ac74f36098e784b60c84708e35cc1f96c6 Mon Sep 17 00:00:00 2001
From: Simon McVittie <[EMAIL REDACTED]>
Date: Wed, 4 May 2022 16:39:05 +0100
Subject: [PATCH] docs: Document new versioning scheme
Signed-off-by: Simon McVittie <smcv@collabora.com>
---
docs/README-versions.md | 60 +++++++++++++++++++++++++++++++++++++++++
docs/README.md | 1 +
2 files changed, 61 insertions(+)
create mode 100644 docs/README-versions.md
diff --git a/docs/README-versions.md b/docs/README-versions.md
new file mode 100644
index 00000000000..097dba1c7b7
--- /dev/null
+++ b/docs/README-versions.md
@@ -0,0 +1,60 @@
+# Versioning
+
+## Since 2.23.0
+
+SDL follows an "odd/even" versioning policy, similar to GLib, GTK, Flatpak
+and older versions of the Linux kernel:
+
+* The major version (first part) increases when backwards compatibility
+ is broken, which will happen infrequently.
+
+* If the minor version (second part) is divisible by 2
+ (for example 2.24.x, 2.26.x), this indicates a version of SDL that
+ is believed to be stable and suitable for production use.
+
+ * In stable releases, the patchlevel or micro version (third part)
+ indicates bugfix releases. Bugfix releases should not add or
+ remove ABI, so the ".0" release (for example 2.24.0) should be
+ forwards-compatible with all the bugfix releases from the
+ same cycle (for example 2.24.1).
+
+ * The minor version increases when new API or ABI is added, or when
+ other significant changes are made. Newer minor versions are
+ backwards-compatible, but not fully forwards-compatible.
+ For example, programs built against SDL 2.24.x should work fine
+ with SDL 2.26.x, but programs built against SDL 2.26.x will not
+ necessarily work with 2.24.x.
+
+* If the minor version (second part) is not divisible by 2
+ (for example 2.23.x, 2.25.x), this indicates a development prerelease
+ of SDL that is not suitable for stable software distributions.
+ Use with caution.
+
+ * The patchlevel or micro version (third part) increases with
+ each prerelease.
+
+ * Each prerelease might add new API and/or ABI.
+
+ * Prereleases are backwards-compatible with older stable branches.
+ For example, 2.25.x will be backwards-compatible with 2.24.x.
+
+ * Prereleases are not guaranteed to be backwards-compatible with
+ each other. For example, new API or ABI added in 2.25.1
+ might be removed or changed in 2.25.2.
+ If this would be a problem for you, please do not use prereleases.
+
+ * Only upgrade to a prerelease if you can guarantee that you will
+ promptly upgrade to the stable release that follows it.
+ For example, do not upgrade to 2.23.x unless you will be able to
+ upgrade to 2.24.0 when it becomes available.
+
+ * Software distributions that have a freeze policy (in particular Linux
+ distributions with a release cycle, such as Debian and Fedora)
+ should usually only package stable releases, and not prereleases.
+
+## Before 2.23.0
+
+Older versions of SDL followed a similar policy, but instead of the
+odd/even rule applying to the minor version, it applied to the patchlevel
+(micro version, third part). For example, 2.0.22 was a stable release
+and 2.0.21 was a prerelease.
diff --git a/docs/README.md b/docs/README.md
index fd0078a5cf4..d9953c08fbb 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -47,6 +47,7 @@ More documentation and FAQs are available online at [the wiki](http://wiki.libsd
- [PSP](README-psp.md)
- [Raspberry Pi](README-raspberrypi.md)
- [Touch](README-touch.md)
+- [Versions](README-versions.md)
- [WinCE](README-wince.md)
- [Windows](README-windows.md)
- [WinRT](README-winrt.md)