Last time we finished a complete CI / CD pipeline capable of detecting source code changes in a GITHUB repository then building those changes on an APPVEYOR builder server and deploying them to a NUGET account.
This time I thought I might add to what we’ve already done by including a NUGET package to our project that will help us generate build specific version numbers. That’s important because the NUGET website will only let us deploy a specific version one time. So, if you deploy, say, version 1.0, then realize you forgot a quick change, make that change and your CI /CD pipeline rebuilds and redeploys your NUGET package, the deploy will fail, since version 1.0 is already sitting on the NUGET site. It makes sense, if you think about it, since there can only be a single “version 1.0”, so how can you deploy a second “version 1.0” on top of it, right?
Problem is, and I guarantee this will happen, you will deploy only to remember a tiny change two seconds after committing to GIT, and, as a result, you will end up with multiple versions of your product on the NUGET site that differ only by a line or two of code. A part of you will realize how much of a pain that is for anyone who uses your NUGET package, but, there won’t be much you can do to alleviate the problem – unless, you add a build number to your product version, which is exactly what we’re going to do today.
What do I mean by a build version? I mean a unique number, usually an incremental number, that’s applied to the existing “version 1.0” product version, the make each deployment unique. So, for instance, let’s say you deploy “version 1.0” and it goes out to the NUGET site as “version 1.0.1” (with build # 1 appended). Now, let’s say you forget a small change you wanted to include as part of “version 1.0”, so you make that change and check in the results,. which causes your CI / CD pipeline to build everything and deploy again, this time with “version 1.0.2”. Without the build number appended, you would have to have deployed something like: “version 1.1”, or “version 2.0”. With the build number, you’re telling everyone “this is just another build of version 1.0”, which is quite a bit different than saying “this is a completely different version than the old, 1.0 version”.
Now, to be sure, if you do want to increment your version, you certainly can do that, and I’ll cover that is this article as well. But, with a build number appended, you’ll only have to remember to increment that number when you get good and ready to.
So how do we add an auto incrementing build number to our projects? I have tried several ways of doing this over the years but I stumbled on a NUGET package from Andrew Arnott called Nerdbank.GitVersioning, and it seems to work fairly well.
So let’s start by opening our CG.Walkthrough project, in Visual Studio. Open the Solution Explorer window, then right click on the G.Walkthrough project and choose the “Managed NuGet Packages” menu choice.
That will display a dialog for adding NUGET packages. Make sure the “Browse” tab is selected, then enter the name of the package we want to add, which is “Nerdbacnk.GetVersioning”.
Finally, click the “Install” button to add the package to our project.
The next thing we need to do is add a JSON file to our solution. So, right click on our project, hit the Ctrl+Shift+A key combination and it should show the “Add New Item” dialog. We want to add a JSON file, but, my installation of Visual Studio doesn’t include that type here so I chose the “Text File” type, then I named the file: “version.json” and clicked the “Add” button.
The result is an empty JSON file added to the solution. Open that file now, in Visual Studio, and add the following text:
“^refs/heads/master$”, // we release out of master
“^refs/heads/v\\d+(?:\\.\\d+)?$” // we also release out of vNN branches
I will confess that I don’t completely understand what all of these values do. Andrew setup his package on one of my NUGET projects and I’ve simply copied that file since then. In any event, this file is required, and the version number should match whatever version you want to publish, which in our case, is version “1.0”.
So, that’s it, really. If you check those changes into your GITHUB repository, your CI / CD build should pick up the change, rebuild your project, and deploy a version 1.0.1 to your NUGET account.
Here is what my build looked like:
Notice, that the MSBuild engine did a NUGET restore, then built the project, then deployed. Notice also that the version of the package was: 1.0.1 – so we know our new versioning scheme is working.
Let’s go look at the NUGET site now, just to make sure that the bits were deployed:
And the package is up there, just as it should be.
So now, every time we build a new version our improved CI /CD pipeline will append a build number to the package before deploying everything to the NUGET website.
If you want to change to, say, version 1.1, then simply edit the version.json file and check the changes into GITHUB. The CI /CD pipeline will take care of everything else.
I’d like to take this opportunity to thank Andrew Arnott for sharing his NUGET package with the rest of us. Nice work Andrew!
So what’s next? Well, I usually include a unit testing project in my NUGET solutions, so, maybe we’ll go look at that.
See ya then!