Automatic Semantic Versioning of Domains with Jargon
Whenever you modify a Domain the changes you make could have a variety of impacts on consuming systems, or none at all. Semantic Versioning (or SemVer) is a versioning strategy that is used to let people know what to expect from new versions of your Domains.
SemVer has strict rules around what version numbers look like and what meaning can be inferred from the version number on its own, including if it’s safe for you to use it or not.
Here’s an example:
v2.1.4
There are three main parts to a Semantic Version, explained here from least important to most important:
- the BugFix/Patch number is last, and is ‘4’ in this example. Increasing it means that you have made a small and inconsequential update to something, like correcting a spelling mistake. Anyone who was using the previous Release can safely use this one, knowing that nothing really important has changed.
- the Feature/Minor number is in the middle, and is ‘1’ in this example. Increasing it means that you have added something new but otherwise the Release is still compatible with the previous one. An example would be adding a new column to a Code Table, or adding a new optional Property to a Class.
- the Breaking/Major number comes first, and is ‘2’ in this example. It is used whenever a breaking change is made. If you’ve removed or renamed something, that will break everyone who was using it, and should result in a new Breaking/Major version number.
Now that we’re all on the same page about SemVer, let’s take a look at what Jargon can do for you to help with some of the heavy lifting.
When creating new Releases
When it’s time to create a new Release, Jargon will examine the Domain’s previous release and calculate the next recommended SemVer number.
Here’s what that looks like:
As you can see, Jargon distinguishes changes that are Breaking, from new features or additions. The list of things that Jargon checks for is quite extensive.
Basic things like:
- Structural changes, such as the design of Classes and Properties
- Names of Classes and Properties
- The types of Properties
More nuanced and opinionated attribute changes that modify the interpretation of properties, such as:
- Making something required that was previously optional with [jargon.required]
- Changing the allowable length of properties specified with [jargon.minLength]
After looking through the changes that Jargon has identified, you have the opportunity to override its recommended SemVer number if you disagree, or have additional information about why the changes are or aren’t breaking.
Inspecting the differences between versions
You can also take a look at the semantic differences between releases (or snapshots) at any time for a Domain by selecting which versions you want to compare on the Domain’s detail page.
Upgrading to newer versions of your Imported Domains
When you start to edit a Domain that has Imports, Jargon will check to see if there are any new versions of those Imports available. You will know there are new versions available when the Import button is highlighted:
Clicking on the Imports button will show you a list of your Imports, and give you links to click on to upgrade. Jargon will look at the SemVer number of the new version, and give you the choice to upgrade to the latest, or non-breaking versions if they’re available.
Taking the non-breaking version should have no real noticable impact on your Domain. You can always checkout the new version’s release notes if you would like to know exactly what’s changed, or perhaps perform your own comparission between versions.
Taking a breaking change means there’s a good chance something in your Domain may break — if it does, Jargon will detect it and report back any errors that it encountered which will help you get everything working again.
Wrapping up:
So that’s a an overview of how Jargon handles Semantic Versions, and some of the automated ways that it can help you stay on top of them.
If you have any further questions about improving how Jargon handles versions, you can:
- check the Getting Started Guide
- leave a comment below
- raise an issue at the jargon issue tracker GitHub repository
- Sign up for a free Jargon account and try it out for yourself
