From: Alan T. DeKok Date: Fri, 3 Oct 2025 16:23:03 +0000 (-0400) Subject: word smithing and updates X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=HEAD;p=thirdparty%2Ffreeradius-server.git word smithing and updates --- diff --git a/doc/antora/modules/ROOT/pages/releases.adoc b/doc/antora/modules/ROOT/pages/releases.adoc index 290d2724b0..b0f2a5f02f 100644 --- a/doc/antora/modules/ROOT/pages/releases.adoc +++ b/doc/antora/modules/ROOT/pages/releases.adoc @@ -5,102 +5,131 @@ in sequence, e.g. 3.0.0, 3.0.1, 3.0.2, etc. After a while it became clear that we needed to separate the releases into "stable" and "feature" releases. -We then move to 3.0.x as a "stable" version, which had only bug fixes -and security enhancements, and 3.2.x as a "feature" version, which had -new features. People needing long-term stability could use 3.0.x, and -know that new releases had minimal changes. People needing new -features could use 3.2.x. +We then move to using 3.0.x as a "stable" version, which had only bug +fixes and security enhancements, and 3.2.x as a "feature" version, +which had new features. People needing long-term stability could use +3.0.x, and know that new releases had minimal changes. People needing +new features could use 3.2.x. -We are following a similar release management process with v4. +We are following a similar release management process with v4, based +on versions: + +Major:: The major version number, e.g. "4" for the forseeable future. + +Minor:: The minor version number, e.g. 4.0, 4.1, 4.2, etc. + +Point:: the "point" release number, e.g. 4.0.1, 4.0.2, etc. == Stable vs Experimental -The v4 releases are split into two streams, based on even / odd -version numbers: +The v4 releases are split into two streams, based on whether the minor +version number is even or odd: -* even numbers are _stable_ and _supported_ releases. e.g. 4.0, - 4.0.1, 4.2, etc. +* minor numbers which are even are _stable_ and _supported_ releases. + e.g. 4.0, 4.0.1, 4.2, etc. - * "point" releases (4.0.1, 4.0.2) are 100% compatible for a stable - release. +** "point" releases (4.0.1, 4.0.2) are 100% compatible within a stable + release. Note that "4.0.1" is a stable release because the minor + number "0" is even, even though the "point" number "1" is odd. -* odd numbers are _experimental_ or _feature_ releases. e.g. 4.1, - 4.1.1, 4.3, etc. +* minor numbers which are odd are _experimental_ or _feature_ + releases. e.g. 4.1, 4.1.1, 4.3, etc. - * "point" releases (4.1.1, 4.1.2) may be incompatible with other - point releases for experimental releases. +** "point" releases (4.1.1, 4.1.2) _are likely to be incompatible_ + with stable releases. "point" releases _may be incompatible_ with + other point releases, even within the same major/minor sequence. ++ + e.g. A 4.1.1 release _may_ have functionality and behavior changed + from the 4.1.0 release. -=== Stable Releases +=== Stable Versions -Stable releases are fully supported by the FreeRADIUS team, and by -https://inkbridgenetworks.com[InkBridge Networks]. Once a stable -release has been made (e.g. 4.0.0), it is feature frozen. The only -changes to it will be security fixes, bug fixes, etc. No behavior -changes will be made, and no features will be added. +Stable versions are fully supported by the FreeRADIUS team via the +https://lists.freeradius.org/pipermail/freeradius-users/[mailing +list]. Stable releases are commercially supported by +https://inkbridgenetworks.com[InkBridge Networks]. -**Stable releases should be packaged by OS vendors.** +Once a stable version has been released (e.g. 4.0.0), it is feature +frozen. The only changes to it will be security fixes, bug fixes, +etc. No behavior changes will be made, and no new features will be +added. -Minor releases will be made for security fixes, bug fixes, etc. So -4.0.1 will be 100% compatible with 4.0.0, except that 4.0.1 will -contain any necessary fixes. +NOTE: Stable versions can be packaged by OS vendors. -This guarantee means that all future versions of a stable release will -be compatible with the initial release. People can install 4.0, and -know that no behavior will change, ever. +Within a stable version, "point" releases will be made for security +fixes, bug fixes, etc. So 4.0.1 will be 100% compatible with 4.0.0, +plus 4.0.1 will contain minor fixes. + +This guarantee means that all future releases of a stable version will +be compatible with the initial version. People can install 4.0, and +know that its behavior will never change across "point" releases". The downside to this approach is that new features will never be added -to a stable release. That's where experimental releases come in. +to a stable version. That's where experimental versions come in. -=== Experimental Releases +=== Experimental Versions -Experimental releases are supported only for testing purposes. Each -experimental release my have breaking changes from a previous stable -release. Each experimental release may even have breaking changes -from a previous experimental release! +Experimental versions are supported only for testing purposes. An +experimental version my have breaking changes from a previous stable +version. A "point" releas of an experimental version may even have +breaking changes from a previous "point" release! -**Experimental releases must not be packaged by OS vendors.** +WARNING: Experimental versions must not be packaged by OS vendors. -Minor releases will be made for new features, security fixes, bug -fixes, etc. Note that 4.1.1 is not guaranteed to be compatible with -either 4.0.x, or even with 4.1.0! +An experimental version will have minor releases made for new +features, security fixes, bug fixes, etc. These releases will often +contain breaking changes. -As such, you should only install an experimental release to test or to -validate new features. We do not recommend using an experimental -release in a production environment. +As such, you should only install an experimental version in order to +test or to validate new features. We do not recommend using an +experimental version in a production environment, unless it is first +validated for your systems. -The purpose of the experimental releases is to test new features, and -to allow testing of breaking changes to the server. +The purpose of an experimental version is to test new features, and to +allow testing of breaking changes to the server. -In some limited situations, an experimental release may be supported +In some limited situations, an experimental version may be supported by https://inkbridgenetworks.com[InkBridge Networks]. However, that -support will be strictly limited to paying customers who use a version -that has been approved in advance by the company. - -Other people are free to use experimental releases, though it will be -at their own risk. The FreeRADIUS team will accept and fix most bug -reports for an experimental release. However, bug reports which note -incompatibilities with a stable release will not be accepted. - -This process is necessary in order to allow a small team to maintain a -large and complex product. +support will be strictly limited to paying customers who use a +specific version that has been approved in advance by the company. + +Other people are free to use experimental versions, though doing so +will be at their own risk. The FreeRADIUS team will accept and fix +bug reports for an experimental version. However, bug reports which +note incompatibilities with a stable version will not be accepted. As +the purpose of an experimental version is to change functionality, +such bug reports are inappropriate. + +The aboce process is necessary in order to allow the small FreeRADIUS +team to maintain a large and complex product. There are many projects +supported by much large teams, which have much less functionality! + +Compared to other limited products, FreeRADIUS version 4 supports +RADIUS, TACACS+, DHCPv4, DHCPv6, BFD, ARP, "cron" jobs, and LDAP +replication, Each of these protocols can interact with databases such +as OpenLDAP, Microsoft Active Directory, MySQL, PostgreSQL, SQLite, +Oracle, IBM DB2, Firebird, ODBC2, or Redis. Each of these protocols +can run complex policies in Unlang, Perl, Python, Lua, etc. + +There is a substantial amount of functionality to support, so the core +team has to be careful with their time. == Rationale The above release process is necessary to balance a number of different goals: -* the desire to never break existing production deployments -* the need to add new features, and to fix existing but broken features +* the need to never break existing production deployments, +* the need to add new features, and to fix existing but broken features, * the need to manage multiple releases with a small team. -The use of a "stable" release means that people can be sure that any -upgrades within that stable release will never break existing -functionality. Any production system which uses a stable release will -never have its behavior changed by upgraded to a new "point" release. +The use of a "stable" version means that people can be sure that any +"point" releases within that stable version will never break existing +functionality. For most software products, the development team spends an enormous amount of time porting features and bug fixes across multiple releases. The release management process outlined here means that the -FreeRADIUS team does not need to take on that effort. +FreeRADIUS team can avoid the bulk of that effort. This release management process will also let the FreeRADIUS team develop new features more quickly, as it is easier to "break" @@ -121,4 +150,4 @@ Stable point releases can contain: Stable point releases cannot contain: * new features -* bug fixes which change the behavior of an existing feature. \ No newline at end of file +* bug fixes which change the behavior of an existing feature.