word smithing and updates

diff --git a/doc/antora/modules/ROOT/pages/releases.adoc b/doc/antora/modules/ROOT/pages/releases.adoc
index 290d2724b077c409dcb18eccf68cad63d72363c7..b0f2a5f02fa78141e34fc014dc0e1333f942d7b9 100644 (file)
--- 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.
 
 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
 
 
 == 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
 
 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
 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:
 
 
 == 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 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
 
 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"
 
 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
 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.