Introducing Jargon — Creating Releases and Importing Domains
About Releases
A Release is an unchangeable version of your domain that is made available to other people to use. Domains in Jargon are Semantically Versioned to help consumers understand when to use a new version, and which version to choose.
When you create a Release, you can change the Domain’s Description and create Release Notes to describe what this release contains, and any help or informaiton that you think is important for other people to know before Importing your Domain.
Unchangeable?
Once a release is published, it cannot change. We do this to make sure that anyone who imports and depends on your domain won’t be impacted by ongoing development to the Domain.
When you’ve developed your Domain further, you can create additional Releases to make those changes available to others.
Semantic Versioning
To help consumers of your Domain know which Release they should choose, or when they should update to a later Release, Jargon uses a concept from releasing software that is called Semantic Versioning, or semver.
A Semantic Version number conveys a lot of information about the nature of this release, including if it’s safe for you to import or not.
Here’s an example:
v2.12.5
There are three main parts to a Semantic Version, explained here from least important to most important:
- the Patch number is last, and is ‘5’ in this example. Increasing the Patch version 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 Minor number is in the middle, and is ‘12’ in this example. Increasing the Minor version number 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 Major number comes first, and is ‘2’ in this example. The Major number is used whenever a breaking change is made. If you’ve removed or renamed something, that will break everyone who was using it, and is a good reason to increment the Major number.
For more information, you can read the official documentation on Semantic Versioning
When you are creating a new Release, Jargon will inspect the changes that you’ve made since the last Release and suggest the next Semantic Version number for you.
Here’s an example of what that looks like:
How to create a Release
Once you’ve made enough changes to your Domain that you think is worthy of a new Release, it’s time to create one.
Head to the Domain Details page either by clicking on your profile image in the top right page, or if you’re on the Domain Editor page (and you’ve saved your work!) by clicking on the name of the Domain in the menu bar at the top of the screen.
Once you’re there, click on the Releases tab, and you’ll see something like this:
Here is where you can create a new Release, but also view the Domain Details page for any previous Releases this Domain has.
Clicking the New Release button will take you the New Release Page:
Ok, let’s go through what’s on this page.
Version: Here is where you can choose the version number of this next Release. Jargon will pre-populate it with what we think makes sense for you, but you’re free to choose one for yourself.
Description: You now have an opportunity to update the description of this Domain that you set when it was created.
Release notes: This is where all your hard work in creating Snapshots with meaningful descriptions pays off! You should be able to more or less copy and paste this list of suggestions into your release notes and give consumers a pretty good understanding of what changes you’ve made. The release notes are written in markdown, and you can preview how they’ll look by clicking on the preview tab.
Remember, that creating a Release is permanent, and you won’t be able to remove it later.
After you’ve created it, your new Release will be the version that people will see when they search, and it will be the only version that people will be able to Import into their own Domain.
About Importing
An Import is how you reuse something from another Domain. As discussed above, any Domain that you wish to Import from must have already published at lease one Release.
Every Domain also has what we call the ‘bleeding-edge’ version. This is the version that you are currently editing and hasn’t been released yet.
You cannot Import the ‘bleeding-edge’ version of a Domain.
Why Import?
Importing allows you to use Classes, Properties, and Code Tables and more from that Domain in yours. It means that you don’t have to reinvent the wheel, and increasese the interoperability of your Domains with others.
Finding Domains to Import
At the top of most pages in Jargon, you’ll see a search bar — this is where you can search for Domains that have at least on Release. It looks like this:
Clicking on any of the results will take you to the Domain Details page for that Domain. Take a moment to look around and try to work out if this is the Domain you’re looking for. You should open up the Domain Editor and look through the Domain, and read the Release notes.
If you’ve decided this is the one, while you’re on the Domain Details page, be sure to copy this’s Domain’s Import string. You can find it here:
That Import string will be used when you actually add an Import to your Domain.
Importing a Domain into yours
When you’re ready to actually import the Domain, open up the Domain Editor for your bleeding-edge version.
In the top menu bar, click the Import button, which will also show you the number of Domains you currently have Imported:
If you already have some Imports, clicking this will list them for you, where you will be able to remove them, or navigate to their Domain Details page.
If it’s your first Import, of you’re adding an additional one, you’ll see this:
Here is where you can paste in the Import string of the Domain that you searched for. You can also type it manually, if you know the name of the Account and Domain that you want to Import.
Note: You can only ever import the latest Released version of a Domain, so you don’t need to worry about remembering version numbers.
Click the ‘Look up’ button, and Jargon will go and try to fetch that Domain. If it can’t find it, it will let you know.
If it does find it, you’ll need to give this import an alias:
An alias is a local name that you will use to refer to this Domain in yours. Aliasing is important to avoid collisions between Classes with the same names.
What did I just Import?
Once you have added an Import, you can browse through the Classes and Properties of your imported Domains.
Clicking on the Import Tree icon in the upper right, will show you the details of your Imports:
Here you can see the list of Imported Domains, and their Classes and Properties. For each of those, you can see their Definition. The white box with black text is how you can refer to this item in your own Domain.
For Example, if you wanted to add a Property that was actually the identification number of Cargo from the shipment Domain, you could:
MyClass
importedIdentificationNumber:shipment.Cargo.identificationThis is also offered in the auto-complete menu as you start to type:
Seeing which Domains Import each other
Saving a Domain with at least one used Imported Class or Property will let you see the Import graph of your Domain:
Here, you can see the deep Imports that your Domain uses, and the Imports that your Imports use.
When you Release a Domain that has used at least one Imported Class or Property, Jargon will record this information which you can see on the Domain Details page.
You can click on any of the listed Domains to go to their Details Page.
Similarly, you can click on the Uses tab, and see which Domains use yours.
Wrapping up
Releasing and Importing Domains can be a little intimidating at first, but it’s an important part of breaking down big Domains into smaller ones.
This is a key concept in Jargon, which greatly helps data interoperability, and encourages Domains to stay current by isolating the parts that need to change from those that don’t.
If there is anything else you really need to know before the next article comes out, you can:
- check the Getting Started Guide
- leave a comment below
- raise an issue at the jargon issue tracker GitHub repository
