Back when I made the first publically available build of Kenc.ACMELib I wanted to go for semantic versioning, but with the default format in Azure DevOps being $(date:yyyy).$(date:MM).$(date:dd)$(rev:.r), the first few builds ended up using that format and I kinda stuck with it.
But - the library has since seen a major rewrite, improving how nonce's are handled, better HTTPClient usage and migrating to System.Text.Json and now is the time to finally move to a proper versioning scheme.
What is semantic versioning?
Semantic versioning is a standard for versioning in software, expressing the version number using the following rules:
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards compatible manner, and
- PATCH version when you make backwards compatible bug fixes.
- Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
semver.org is dedicated to the spec for semantic versioning, in it's various versions.
Why use Semantic versioning
Following the rules stated above, makes it clear to developers using a library, whether or not an upgrade to the latest version is expected to have any breaking changes or require any effort.
This is not only important for developers to know when upgrading the library used in appliations, but also when taking dependencies on library that take a dependency on library, due to how .net handles changes to function definitions.
In short, an update to a library might cause a binary-incompatibility, even when re-building will succeed.
For libraries that take a dependency on a library, this is especially important to keep in mind, as a dev on an application is technically free to update the bottom of the dependency tree and redirect loading of the dependency tree to the updated version. This is not possible if the bottom of the dependency tree has a binary-incompatibility and will fail to call the referenced function at runtime, resulting in a MissingMethodException.
Microsoft has guidance out for how to handle breaking changes in dotnet, dotnet breaking changes
Unlisting previos versions
Nuget feeds support unlisting a version, so it doesn't show up in search results, but if you know the exact version you are looking for, it can still be downloaded.
This is neccessary, as users using v1.0.5-beta would be prompted to upgrade to 2021.4.10.1 in the nuget package manager dialog of Visual Studio or similar solutions.
As a result, the following versions has been unlisted from nuget.org
| Version |
|---|
| 2021.4.10.1 |
| 2020.9.5.1 |
| 2020.5.15.5 |
| 2019.11.17.1 |
| 2019.9.23.1 |
| 2019.9.22.4 |
| 2019.9.21.3 |
| 2019.3.24.1 |
| 2019.1.3.1 |
| 2018.11.23.2 |
| 2018.11.19.1 |
| 2018.11.15.3 |
| 2018.11.12.3 |
Upgrading to Kenc.AcmeLib 1.0.5-beta
Kenc.ACMELib 1.0.5-beta is considered a breaking change over 2021.4.10.1 and earlier versions.
Most noteable changes: ACMERestClient no longer exists, the constructor now takes a System.Net.HttpClient. Constructor has changed to take the base uri as a System.Uri, instead of as a string. Classes has moved from the namespace "Kenc.ACMELib.ACMEEntities" to "Kenc.ACMELib.ACMEObjects" Moving from Newtonsoft to System.Text.Json
Refer to the Github PR for examples on upgrades.
0 comments