Versioning

Overview

NFluent follows a 'semver' like policy:

1. Versions follows the format Major.Minor.Patch
2. Major is incremented in case of breaking change (x.y.z => (x+1).0.0)
3. Minor is incremented when new features are introduced (x.y.z => x.(y+1).0)
4. Patch is incremented for bug fix (x.y.z => x.y.(z+1))

From a context perspective, NFluent has a relatively large API set (mostly checks) which forces us to somehow relax this convention. Also bear in mind that NFluent is a trunk based projects, which implies a strong linear history of changes. Note that the error messages (generated when a check fails) are not considered as part of the API. So you should expect them to change across versions as we work constantly on improving them.

Advised upgrade strategy

You should upgrade NFluent on a regular basis. We strongly recommend you upgrade as soon as a new version appears to make sure you have the latest fixes.

What should you do/expect when you upgrade NFluent?

The first version number (major) has changed (x.y.z => x+1.y'.z')

• You must read the release notes to understand where breaking changes have been introduced. You should then estimate what effort the migration will change and plan it accordingly.
• The recommended migration strategy is to build with the new version and fix build errors, if any.

The second version number (minor) has changed (x.y.z => x.(y+1).z')

• You should read the release notes to discover what features have been introduced.
• The upgrade should be transparent, i.e. without any build errors.
• You may have some warnings due to check flagged as Obsolete (they will be documented in the readme), you should migrate relevant checks to the new syntax.
• If you have build error(s), please open an issue on GitHub so we can address the problem.
• in some cases, you may have tests that fail with the new version, whereas they were successful until then. The likely explanation is that a NFluent's issue has been fixed. Read the release notes, the change should be documented. If you disagree with the result, please open a Github issue.

The patch version number has changed (x.y.z => x.y.(z+1))

• The upgrade should be transparent, i.e. without any build errors.
• You should read the release notes to discover what issues have been fixed.
• in some cases, you may have tests that fail with the new version, whereas they were successful until then. The likely explanation is that a NFluent's issue has been fixed. Read the release notes, the change should be documented. If you disagree with the result, please open a Github issue.

Beta versions

We regularly publish beta versions. They are available through MyGet dupdobnightly channel.

MyGet is an alternative to Nuget.org. To access NFluent beta, you just have to add it as a source in your Nuget configuration. You can do this either through VisualStudio GUI or through the CLI. You just need to do it once, then you will see NFluent betas alongside other versions. You can see detailed documentation and how to on MyGet site.

Beta versions goes through the same quality gates as the official/stable releases. They have no known bugs and are production ready. But upcoming features may not be stabilized yet and you should expect API differences (often naming related) between a beta and the next stable release. The upcoming features are listed in the release notes.

Policy

Major version

We increase the major version number in case of significant breaking change. We do increase the major version number when the signature of check(s) change without having been marked as [Obsolete] in previous version(s).

We shall increase the major version number in case of behavioural change of checks, i.e. when a check fails when it succeeded before or vice-versa. We will not increase the major version number when the behaviour was not fully documented or not obvious.

These rules apply to 'checks' and user facing features. We apply a similar, but more relaxed policy regarding extensibility features. Typically, this implies that breaking changes may be introduced in extensibility APIs without an increase of the major version number.

Minor version

Most releases will have an increased minor version number.

Patch version

We increase the minor version number when the release mostly contains bug fixes. But those release may also include some new checks. This typically happens when need to release a bug fix for a release when we already have new checks ready.