From cccad933a083c8500f0e0267befa460b8d48f76f Mon Sep 17 00:00:00 2001 From: Sam Lantinga Date: Mon, 7 Apr 2025 10:22:42 -0700 Subject: [PATCH] Updated version documentation to match SDL 3.x practice --- docs/README-versions.md | 68 +++++++++++++++++------------------------ 1 file changed, 28 insertions(+), 40 deletions(-) diff --git a/docs/README-versions.md b/docs/README-versions.md index 097dba1c7b..6c2d920c86 100644 --- a/docs/README-versions.md +++ b/docs/README-versions.md @@ -1,60 +1,48 @@ # Versioning -## Since 2.23.0 +## Since 3.2.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. +* If the minor version (second part) and the patch version (third part) is + divisible by 2 (for example 3.2.6, 3.4.0), 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). + indicates bugfix releases. Bugfix releases may add small changes + to the ABI, so newer patch versions are backwards-compatible but + not fully forwards-compatible. For example, programs built against + SDL 3.2.0 should work fine with SDL 3.2.8, but programs built against + SDL 3.2.8 may not work with 3.2.0. - * 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. + * The minor version increases when significant changes are made that + require longer development or testing time, e.g. major new functionality, + or revamping support for a platform. Newer minor versions are + backwards-compatible, but not fully forwards-compatible. For example, + programs built against SDL 3.2.x should work fine with SDL 3.4.x, + but programs built against SDL 3.4.x may not work with 3.2.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. +* If the minor version (second part) or patch version (third part) is not + divisible by 2 (for example 3.2.9, 3.3.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. + * The patchlevel or micro version (third part) increases with each prerelease. * Prereleases are backwards-compatible with older stable branches. - For example, 2.25.x will be backwards-compatible with 2.24.x. + For example, programs built against SDL 3.2.x should work fine with + SDL 3.3.x, but programs built against SDL 3.3.x may not work with 3.2.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. + * Prereleases are not guaranteed to be backwards-compatible with each other. + For example, new API or ABI added in 3.3.0 might be removed or changed in + 3.3.1. 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. + * Only use a prerelease if you can guarantee that you will promptly upgrade + to the stable release that follows it. For example, do not use 3.3.x + unless you will be able to upgrade to 3.4.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. + should 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.