Introduction to Ballerina Semantic Versioning Validator
Before getting started…
If you are someone who accidentally came across this blog, this is a part of the blog series where I’ve been sharing some of the cool features and also my experiences as a developer of this new programming language called Ballerina, powered by WSO2.
Ballerina is a general-purpose and open-source programming language, specialised in micro-services and easy integration.
Building this language platform and its ecosystem has been a massive effort of more than 5 years with over 300 contributors.
Well that’s enough.. back to the Story!
As a part of this evolved Ballerina ecosystem, Ballerina has its own globally hosted package management system, The Ballerina Central. And currently the Ballerina package/library versioning strategy is also based on the semantic versioning specification.
Semantic versioning is a well-known and widely adopted concept in the software world, mainly to overcome the problem of dependency hell.
However, as a Ballerina library developer you are free to choose the version at your will when publishing your library to the Ballerina central, because the Ballerina platform itself hasn’t been providing any validation/enforcing mechanism to ensure the semantic versioning compliance between sub-sequent package releases. And This could result in releasing new versions of Ballerina libraries that are compatible only by their version and not by the implementation.
An Exemplar: The Elon’s Problem
Let’s say developer Elon is working on a Ballerina library that provides a set of Ballerina string related utilities. Furthermore, he has already published v1.0.0 to the central (under org name elon and package name stringUtils) and it contains the below public API (i.e. function).
And another developer, Jeff has been using Elon’s library in his code in the following way.
Then, Elon decides to change the same function in the following way (changing the defaultable parameter endIndex to a required parameter) and to publish to the Ballerina central under the version 1.0.1 (as a patch release) of the library.
Now, this one simple change in Elon’s new library release will cause the below compilation error in Jeff’s existing code.
error: missing required parameter 'endIndex' in call to 'substring()'Therefore, despite the fact that the version 1.0.1 is supposed to be backward-compatible with the version 1.0.0 (as per the semver specification), they are not compatible in terms of the implementation anymore.
Ballerina Semver Validator CLI Tool
The Ballerina SemVer validator is a new experimental CLI tool that aims to minimum the above type of versioning compatibility issues in a programmatic approach.
Ballerina semver validator is capable of validating Semantic Versioning compatibility the local package changes against any previously published version(s) in Ballerina Central.
Currently, the tool can be used to:
- list down the source code differences (along with its compatibility impact) between the local and any published versions in Ballerina central
- suggest the new package version based on the compatibility impact of source code changes
How Ballerina semver validation works
The below sequence diagram illustrate the high-level overview of the default semver validation flow and, the platform components which are being used during the validation flow.
As you notice, the approach taken is to pull the closest compatible release package(or any other release version, if specified) from the central and partially compile the both versions of the package source code. Then a set of comparators will and all necessary analysis is performed in that context, where the resources like syntax trees and type information are available. Also in order to perform these different phases (i.e. package resolution, source code comparison, diff computation, version calculation, etc) the tool makes use of a collection of Ballerina compiler/platform APIs such as Central API, Parser API, and the Project API.
However, in this chapter we will be more focused on the functionality and the usage of the tool and therefore all the in-depth explanations on the implementation-level decisions and details are planned to be discussed under a separate blog of this series.
Well… Now its time to get your hands on the Ballerina semver validator and to take care of the Elon’s problem :D
Prerequisites
- Download and install Ballerina SwanLake Update 2 (or higher) version.
- Clone Elon’s stringutils v1.0.0 demo source code from the repository.
Checkout to the package root directory and open the stringutils.bal file in your editor.
Add the following changes to the existing source code.
i. Change defaultable parameter endIndex to a required parameter.
ii. Add some API documentation for the function.
iii. Add comment(s) within the substring function body.
After doing all of the changes above, the new source code should look similar to the below code sample.
As the final step, checkout to the package root directory from your terminal and execute the bal semver command. The command output is shown below.
$bal semver
checking for the latest compatible release version available in central…current version: 1.0.0
compatibility impact (compared with the release version ‘1.0.0’): backward-incompatible changes detected
suggested version: 2.0.0
As you notice, the tool notifies that the new changes contains one or more backward-incompatible changes compared to the last release version and also suggests the version 2.0.0 (a major version bump) as the minimum compatible version for the next release. And in that way, this new tool is capable of detecting all the compatibility violations of your new library release prior pushing to central and, it can even help you choosing a new version! (How cool is that? :D)
Also, if you wish to see the source code diff between the package versions (along with the compatibility impact of each individual change), you can simply use the --show-diff option with the same command.
$bal semver --show-diff
checking for the latest compatible release version available in central…================================================================
Comparing version ‘1.0.0’(local) with version ‘1.0.0’(central)
================================================================
[+-] package ‘stringutils’ is modified [version impact: MAJOR]
[+-] module ‘stringutils’ is modified [version impact: MAJOR]
[+-] function ‘substring’ is modified [version impact: MAJOR]
[++] documentation is added [version impact: PATCH]
[+-] kind of parameter ‘endIndex’ is changed from ‘DEFAULTABLE_PARAM’ to ‘REQUIRED_PARAM’ [version impact: MAJOR]
[+-] function body is modified [version impact: PATCH]current version: 1.0.0
compatibility impact (compared with the release version ‘1.0.0’): backward-incompatible changes detected
suggested version: 2.0.0
As you can see, now the tool will also list-down all the impacted source changes along with the change type (addition/removal/modification) and the severity. So you are able to precisely see how each individual source change has affected the semver compatibility of your library.
You can execute
bal semver --helpfor the CLI help text to view all the other available command options.
Whats next?
As mentioned earlier, the Ballerina semver validator is introduced as an experimental CLI tool in Ballerina Swan Lake Update 2 version. For the next updates, we are working on a comprehensive specification which precisely determines how the semantic versioning compatibility should be decided between package versions. With that, we are expecting to improve the tool to go beyond analysing the source code (e.g. analysing the dependencies, package metadata, resources, compiler extension information, etc) and we’ll also be working on smoothing out the remaining rough edges.
Thanks for your time and feel free to reach out and contribute for this tool by providing your ideas/suggestions and by reporting issues. Hope to see you soon with the next blog of the series :) Happy coding!
