Each abuild release is assigned a version number. For abuild releases, we use the following version numbering convention:

major.minor.prerelease-or-update

The major field of the version number indicates the major version number. It changes whenever a major release is made. A new major release of abuild represents a wholesale change in the way abuild works. Major release are expected to be very infrequent.

The minor field of the version number indicates the minor version number. It changes whenever a minor release is made. A minor release is an incremental release that may introduce significant new features, fix bugs, or change the way some things work, but it will not fundamentally shift the way abuild works. We impose tight restrictions on the introduction of non-backward-compatible changes in minor releases as discussed below.

The prerelease-or-update field can indicate either a prerelease version or an update release of a specific minor version. A prerelease is an alpha or beta release or a release candidate that precedes a regular release. An update release may contain bug fixes or new features as long as no non-compatible changes are made to existing functionality. Allowing new non-breaking features to be introduced in an update release makes it possible to add features to abuild incrementally while still guaranteeing as much compatibility as possible. There is no support for a prerelease of an update to a specific minor version (like 1.1.1.b1).

Before a regular major or minor release, there may be a series of alpha releases, beta releases, and release candidates. In those cases, the prerelease-or-update field of the version number is either “a”, “b”, or “rc” followed by a number. The prerelease version numbers clearly indicate which regular release the prerelease applies to. For example, version 1.3.a4 would be the fourth alpha release preceding the release of version 1.3.0.

After any major or minor release, it is possible that a small problem may be corrected in a bug-fix release. In such a release, the prerelease-or-update field contains a number that indicates which bug-fix release this is. For example, version 1.2.1 would be a bug-fix release to version 1.2.0.

Historical note: the first release of abuild 1.0 was just version 1.0, not version 1.0.0. The use of “x.y.0” was introduced with version 1.1.0 so that “abuild x.y” could unambiguously refer to all update releases of minor version x.y rather than just the first.

In a new major release of abuild (e.g., version 2.0.0), there is no promise that changes will be backward compatible, nor is there any expectation that configuration files from older abuild releases will work with the new version. When possible, care will be taken to mitigate any inconvenience such as providing upgrade scripts.

In each new minor release of abuild, there may be new features and backward-compatible changes. In minor releases, we adopt a stricter policy regarding non-backward-compatible changes. Specifically, non-backward-compatible changes may be introduced only if the changed construct generated a deprecation warning in the previous minor release. In other words, if particular construct in version 1.3 is going to be dropped or changed in a non-compatible way, the change can't be made until version 1.5. In version 1.4, the new way may work, but use of the deprecated construct must still work and must generate a warning. The old way can be dropped entirely in version 1.5 once users have had a chance to adjust their configuration files. In that way, users who take every minor release upgrade can be guaranteed that they will not experience surprise non-compatible changes, and they will not have to update their configuration files at the same time that they upgrade abuild.

With alpha releases, there is no commitment to avoiding non-compatible changes. In particular, a feature that was introduced into abuild during an alpha testing period may be modified in non-compatible ways or dropped entirely during the course of alpha testing. During beta testing, every effort will be made to avoid non-compatible changes, but they are still allowed. No non-compatible changes will be made from the first release candidate through the next minor release.

Specific exceptions may be made to any of the above rules, but any such exceptions will be clearly stated in the release notes or the documentation. It may happen, for example, that a particular new feature is still in development when a release is made. In that case, the release notes may declare that feature to still be alpha, in which case non-compatible changes can be introduced in the next release.

We'll clarify with some concrete examples. Suppose a new feature is planned for version 1.4 of abuild. It would be okay if the first implementation of that feature appeared in version 1.4.a2 and if the feature were changed in a non-compatible way in 1.4.a6. However, after version 1.4.0 was released, the next non-compatible change would not be permitted until version 1.5.a1, and even then, the feature as it worked in version 1.4.0 would still have to work, though a deprecation warning would be issued. The old version 1.4.x way of doing things could stop working altogether in version 1.6.a1. It is also okay to add a new feature within a minor release. For example, it's okay if 1.0.3 adds some feature that wasn't there in 1.0.2 as long as everything that worked in 1.0.2 works the same way in 1.0.3. In other words, although everything that worked in 1.0.2 must work in 1.0.3 , there's no expectation that everything that works in 1.0.3 must have worked in 1.0.2.