Semantic Versioning
0 (0 Likes / 0 Dislikes)
Semantic Versioning
with Addison Berry
The term "semantic
versioning," or SemVer,
is a way of numbering
a software release.
And it's something that's
being adopted more and more
widely by different
software projects.
So in this tutorial,
we're just going
to walk through a few basic steps.
We're going to explain exactly
what semantic versioning, how
that works.
We'll talk about
some of the benefits
and why people are switching
over to semantic versioning.
And we'll wrap up by showing
how you can get more information
and the actual
specifications for it.
So semantic versioning,
as I said earlier, SemVer
is a short form of it that
you may see out there.
So if someone was
talking about SemVer,
that's what they're talking
about, semantic versioning.
And it uses a three-number system
instead of a two-number system
for a release number
on a piece of software.
So you might be familiar
with software release numbers
that do something
like 1.0, 1.1, 1.2.
And with semantic
versioning, we use three.
And we're going to take a
look at that in a second
to see what that means
and what it looks like.
One of the important things
about semantic versioning
as well is that it
requires a public API.
So if you are saying you're
using semantic versioning,
you have to have some kind
of publicly declared API
because the semantic
versioning numbering system is
dependent on whether; things like
whether or not you're breaking
your API or how the version
is changing the API.
So if you don't have something
that's sort of publicly declared
that can be sort of looked at
and measured against so you can
actually see is this actually
changing and breaking something
or not, then the semantic
versioning numbering
doesn't tend to make,
well, as much sense.
So it's an assumption that you
have a public API that people are
tracking and able to
use and interact with.
And then with semantic
versioning, you're
letting them know what
changes have been made
to the software that
affects the API.
And then they can make a
decision on whether or not
they want to upgrade, or
if they have to upgrade,
what other changes they're going to
have to make in their dependencies.
So let's take a look at the
actual numbers themselves.
So here's just a made
up version number.
And you can see that
we have three numbers.
So the first number is
the major version number.
The second is minor version.
And then the third
number is a patch number
basically meant for bug patching.
So let's walk through each
of the numbers individually.
So a major version, whenever you
increment the major version number,
you are actually breaking the API.
There's no backwards
compatibility with the old API.
So something-- like
in this instance, this
is version 8 of this software.
This is not backwards compatible
with the version 7 of the software.
For a minor version, this does
not break backwards compatibility
with the version number before it.
So 8.2 is backwards
compatible with 8.1.
We didn't actually break
anything major here.
This number is used for things
that are like new features
or big changes that are
being made in the software,
but it's not breaking
backwards compatibility.
The last number, this
third number, is the patch
number, which is
meant for bug fixes.
So every time we have a
version of the software,
every time we do security
updates or fix bugs
or those kinds of things,
that just gets a patch number.
And that should never break
backwards compatibility.
If you need to break backwards
compatibility to fix those bugs,
then you're going to end
up having to increment
to a whole new major version number.
So that is the basic
numbering system.
That's why there are three numbers.
They each indicate
different kinds of changes.
So by looking at the
number, you can immediately
tell sort of what the state
of the piece of software is.
So in this instance, we're
on the eighth major version.
So there have been
seven changes that
have broken backwards
compatibility in the past.
We're on the second minor version,
which means there have been two
feature changes and
additions have been made.
And we're on the sixth
bug fix or patch,
so there have been six bug fixes
to the second minor version here.
So after we did our
second big feature push,
we've had six bugs that
we've fixed in the meantime.
So if we had another bug
that came along from 8.2.6,
we would increment our release
8.2.7 for that bug fix.
But everything else is
essentially the same.
Now, if we actually come along and
we do a new feature, like we're
really changing stuff and adding
some new stuff to the site,
we're going to increment
the minor version up to 3
and that's going to reset the
patch to 0, because there are
no actual bug fixes
for version 3 yet.
So 8.3.0.
If we get to actually breaking
the backwards compatibility
with the API, then
we're going to increment
the major version number up to 9.
And we're going to zero out
all of the rest of the numbers
because we don't have any
features or bug fixes in version 9
yet when we first release it.
And we would begin all over.
Again our first
feature would be 9.1.0,
and then our first bug fix
to that would be 9.1.1.
So that's the basics of the numbers
and what those numbers signify.
And it's very clear and distinct
what each number is representing.
So when you look at the number,
you should have a very good sense
of what the status of
that code is, particularly
in comparison to previous versions.
Now, before you actually
get to releasing something
and you're working on
it, of course you also
want to keep track of your versions
before you're talking about API
changes and features and
those kinds of things.
So with initial development
with semantic versioning,
you're going to use the
major version number of 0.
So my first feature as I
begin to work on my code
is going to be 0.1.0.
That's the first feature.
And as I add features, I will
increment the minor number.
And of course, bug fixes
will get the patch number.
You can also use pre-release
strings with semantic versioning.
So things like alphas and
betas and release candidates.
You can also put in
numbers with those.
And you would just append that
to the end of the release.
So your pre-release, before you
actually release a real version,
would be 1.0.0 because that's where
your public release-- like I've
been doing all of my
development, I'm ready to go.
I'm going to put it out there
for the public to begin using.
That's 1.0.0.
So if I was doing my alpha and
then beta and release candidate
for that particular release, I
would just put that at the end,
as you can see here in the slide.
So development, you're
going to start with 0.
When you first make your software
publicly available for other people
to use, you start off
with a major version of 1.
And then you'll increment
the three different numbers
as we just discussed
in the previous slides.
So why go through this?
Why have three numbers
and all of this like very
specific definition
of what's going on?
One of the main
motivations for doing this
was just to make really
clear when you have
compatibility or
dependency problems.
If someone is using your
software, and especially
if they're using an API and
they're using it in a code way
and they've written other
code that's dependent on it
in some way, when
those things change
it affects everybody else's
work that they've done.
And so it makes it very clear from
the version number what is going
on in terms of my code is compatible
with or dependent upon 8.2.x.
Or 8.x.x.
People can decide
what they need to do.
But if you break that API,
then people will immediately
know that their compatibility and
dependencies are probably broken
and then they're going to
need to update their stuff.
So just to make it very clear
which version people are using
and what that actually
means, what the implications
are for other code that
may be dependent on it.
It also really encourages
well-defined APIs.
In order for you to know
whether you're breaking an API
or if you are still fully
backwards compatible,
you need to have a pretty clear
idea of what your API is doing
and how people are using it.
And so it really helps to clearly
define that and then when you make
changes to think about in terms
of that backwards compatibility
in very clear terms.
And that just is
better for everybody
in terms of documenting
things and making sure
that people who are
using the software
aren't caught by surprises.
It can also help with
upgrade decisions.
If I'm just an end
user of some software
and I see that a bug
fix has come out,
chances are that's
a good thing for me
to upgrade to get that bug fixed.
But I also know it's not going to
majorly change anything in terms
of how I'm used to
using the software.
If I see that the minor
version has changed,
then this is a new feature.
There's some new
change that's going on.
But it's not going to break
how the software works,
so how I'm used to it working in
terms of backwards compatibility.
And then if a major
version comes along,
I know that things are going to
be likely very, very different.
And it can change how I make my
decision about whether or not
I should upgrade my software or not.
It's just a clearer message to
people who are using the software.
So all around, it's just making
things clearer and more explicit,
which is, of course, just going
to be beneficial to everybody,
including developers of software so
that you have a clear idea of what
it is you're creating
and communicating that
well to the people who are using it.
If you want to find out more details
and get the actual specification
for this, you can go to semver.org.
And that is where you actually will
find the explicit list That's where
it says things like,
you have to have
a public API, how the
numbering system works.
It also talks about some
edge cases and other things
that I might not have covered
in this short presentation.
And it gets versioned just
like semantic versioning,
so you can always tell if
there's been a major change
in the specification by the number
of the semantic versioning website.
So in this short tutorial, we've
covered what semantic versioning is
and how we actually use it with the
three-number system, why this is
a good thing, and go check out
more information at semver.org.