Release Management
For most of the v3 lifespan, we had released one version after another 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 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, 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 whether the minor version number is even or odd:
-
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 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.
-
-
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) 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 Versions
Stable versions are fully supported by the FreeRADIUS team via the mailing list. Stable releases are commercially supported by InkBridge Networks.
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.
| Stable versions can be packaged by OS vendors. |
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 version. That’s where experimental versions come in.
Experimental Versions
Experimental versions are supported only for testing purposes. An experimental version my have breaking changes from a previous stable version. A "point" release of an experimental version may even have breaking changes from a previous "point" release!
| Experimental versions must not be packaged by OS vendors. |
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 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 an experimental version is to test new features, and to allow testing of breaking changes to the server. Each experimental release will note all behavior changes, including breaking changes in the release notes.
In some limited situations, an experimental version may be supported by InkBridge Networks. However, that 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 above 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 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" 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 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" backwards compatibility. We can change core functionality from 4.0 to 4.2, without worrying about taking down production systems which are using 4.0. Instead, those systems can stay on 4.0, and any systems needing new functionality can use 4.2.
Guidelines
The following are guidelines for code which goes into a release.
Stable point releases can contain:
-
bug fixes
-
security fixes
Stable point releases cannot contain:
-
new features
-
bug fixes which change the behavior of an existing feature.
Developers
Changes to stable branches
All changes to stable branches must undergo a review process to ensure adequate testing is in place, and to verify that they are backwards compatible with previous releases.
A PR must be raised in order to move commits into a stable branch from the experimental branch, and that PR must pass all CI checks, and be reviewed by at least one other core developer.
| Breaking changes are only permitted, IF they are added behind a feature flag, that preserves the previous behaviour by default. |
Changes to experimental branches
Minor changes to experimental branches are permitted. Other work may need peer review. Developers must self-classify change sets to determine if peer review is needed.
The main criteria for requiring peer review are: - Will the change break backwards compatibility (this is fine, but needs to be understood and documented). - Is it a code area with many untested paths, or poorly structed code that’s hard to reason about. - Is the code likely to have widespread impacts on the rest of the code base, will it be difficult to change later, will it have widespread negative impacts if it’s not architected correctly.
-
Major refactoring over 1000 +/- changes LoC
-
Changes to parsing that would break comptibility with previous syntax.
-
Changes to the behaviour of keywords that are not backwards compatible.
-
Any alterations to state machines i.e. new states, and changes to pre/post conditions.
-
Changes to async I/O code other than trivial fixes. Code paths here are notoriously undertested and need careful to review to ensure there are no unintended consequences.
-
Conversions of existing modules to async I/O.