I am looking forward to implementing a daily build for an upcoming project.
But before doing that, I need to know how to properly version an assembly.
I have the following concerns:
Should each assembly have an independent version number or should they all share the same version?
Should I use a * version for build and revision?
Is revision relevant to daily build?
We stamp all the assemblies within our products with the same version number using the following steps:
Link all assemblies to an
AssemblyInfoCommon.cs containing the
version number info: see here
for an example.
Generate the AssemblyInfoCommon.cs file as part of the build
using (in our case) the NAnt asminfo task, Cruise Control .NET and the SVN revision labeller
In our case, we don't use the * version. All deployed versions are built on the build server. We don't worry about version number on our desktops.
The answer really depends on what you are trying to accomplish with the assembly version numbers. If you are doing a ClickOnce deployment and want to do independent downloads of updated assemblies, you will need to have each assembly independently versioned -- otherwise, I think it's often nice to have assembly versions match the software release number. In more complex scenarios you may need another strategy.
A scheme I used at a prior company was major.minor.revision.build -- so in version 1.0 of the product, the assembly version and assembly file version on each assembly was 1.0.0.1129 (for example). This made it easy to match up what assemblies were part of which software release, down to the build number. We accomplished this using a pre-compilation search and replace in each AssemblyInfo.cs file to replace a token with the version numbers provided by our automated build process.
So Each assembly should have the same version which is typically a combination of the release version ie 3.4 + the build number which is a sequence that represents the number of times that release has been compiled on the build server. The revision is relevant because it demonstrates the number of builds that you have created for that release. You can really do this in one of 2 ways. The first way would be that if you planned a release ie 3.4 then when you start working on that release then that is your major version number and your minor version number increments with the build. Another way to do this is to tightly control the build versions in that when you are ready to perform your release to QA / Regression you set your major version to 3.4 and you leave your minor version number to 0. You keep things tightly controlled this way until you release. This way you can control your service pack numbering through the minor version number. Hope this helps.
I would normally agree that all assemblies should have the same version number; however, I would make one caveat to that. If one of the assemblies is used somewhere else outside of this project or if it is considered it's own project it should have it's own version number. It should also probably be moved out of that solution and into it's own. The only reason I mention this is that I have seen numerous occasions where people have an assembly that's used in a couple of other places, but mainly in one place and they try and keep the version straight. It's a bad idea to do that. I think the Single Responsibility Principle applies at the solution/project level as well.
As far as numbering goes, I agree with Guy Starbuck (major.minor.revision.build). That's the way I've always done it and it has always worked well.
We have a large app (hundreds of assemblies) with frequent releases (about 1 a month). We went for the "give every assembly the same version" but its a constant source of fustration to me that assemblies for 1 version are completely incompatible with those from another, despite the fact that the interfaces of these assmblies rarely (if ever) change.
If this is case for you then you might benefit from versioning assemblies separately - each time you update your assembly only bother to increment the version number in cases where you actually want to break assembly binding (for example if the interface changes, or the changes are otherwise significant enoigh that you want to prevent someone from accidentially using the previous version).
Related
I am looking for a tool to manage the collection of binary files (input components) that make up a software release. This is a software product and we have released multiple versions each year for the last 20 years. The details and types of files may vary, but this is something many software teams need to manage.
What's a Software Release made of?
A mixture of files go into our software releases, including:
Windows executables/binaries (40 DLLs and 30+ EXE files).
Scripts used by the installer to create a database
API assemblies for various platforms (.NET, ActiveX, and Java)
Documentation files (HTML, PDF, CHM)
Source code for example applications
The full collected files for a single version of the release are about 90MB. Most are built from source code, but some are 3rd party.
Manual Process
Long ago we managed this manually.
When starting each new release the files used to build the last release would be copied to a new folder on a shared drive.
The developers would manually add or update files in this folder (hoping nothing was lost or deleted accidentally).
The software installer script would be compiled using the files in this folder to produce a SETUP.EXE (output).
Iterate steps 2 and 3 during validation & testing until release.
Automatic Process
Some years ago we adopted CI (building our binaries nightly or on-demand).
We resorted to putting 3rd party binaries under version control since they usually don't change as often.
Then we automated the process of collecting & updating files for a release based on the CI build outputs. Finally we were able to automate the construction of our SETUP.EXE.
Remaining Gaps
Great so far, but this leaves us with two problems:
Rebuilding Assemblies The CI mostly builds projects when something has changed, but when forced it will re-compile a binary that doesn't have any code change. The output is a fresh build of a binary we've previously tested (hint: should we always trust these are equivalent?).
Latest vs Stable Mostly our CI machine builds the latest versions of each project. In some cases this is ok, but often we want to release an older tested or stable version. To do this we have separate CI projects for the latest and stable builds - this works but is clumsy.
Thanks for your patience if you've got this far :-)
I Still Haven't Found What I'm Looking For
After some time searching for solutions it seems it might be easier to build our own solution, but surely someone else has solved these problems before!?
What we want is a way to store and manage binary files (either outputs from CI, or 3rd party files) such that each is tagged with a version (v1.2.3.4) that allows:
The CI to publish new versions of each binary (but reject rebuilt versions that already exist).
The development team to make a recipe for a software release (kinda like NuGet packages.config) that specifies components to include:
package name
version
path/destination in the release folder
The Automatic package script to use the recipe collect the required files, and compile the install package (e.g. SETUP.EXE).
I am aware of past debates about storing binaries in a VCS. For now I am looking for a better solution. That approach does not appear ideal for long-term ongoing use (e.g. how to prune old binaries)... amongst other issues.
I have tried some artifact repositories currently available. From my investigation these provide a solution for component/artifact storage and version control. However they do not provide tools for managing a list of components/artifacts to include in a software release.
Does anybody out there know of tools for this?
Have you found a way to get your CI infrastructure to address these remaining issues?
If you're using an artifact repository to solve this problem, how do you manage and automate the process?
This is a very broad topic, but it sounds like you want a release management tool (e.g. BuildMaster, developed by my company Inedo), possibly in conjunction with a package management server like ProGet (which you tagged, and is how I discovered this question).
To address some specific questions you have, I'll associate it with a feature that would solve the problem:
A mixture of files go into our software releases, including...
This is handled in BuildMaster with artifacts. This video gives a basic overview of how they are manually added to releases and deployed to a file system: https://inedo.com/support/tutorials/buildmaster/deployments/deploying-a-simple-web-app-to-iis
Of course, once that works to satisfaction, you can automate the import of artifacts from your existing CI tool, create them from a BuildMaster deployment plan itself, pull them from your package server, whatever. Down the line you can also have your CI tool call the BuildMaster release management API to create a release and automatically have it include all the artifacts and components you want (this is what most of our customers do now, i.e. have a build step in TeamCity create a release from a template).
Rebuilding Assemblies ... The output is a fresh build of a binary we've previously tested (hint: should we always trust these are equivalent?)
You can mostly assume they are equivalent functionally, but it's only the times that they are not that problems arise. This is especially true with package managers that do not lock dependencies to specific version numbers (i.e. NuGet, npm). You should be releasing exactly the same binary that was tested in previous environments.
[we want] the development team to make a recipe for a software release (kinda like NuGet packages.config) that specifies components to include:
This is handled with releases. A developer can choose its name, dates, etc., and associate it with a pipeline (i.e. a set of testing stages that the artifacts are deployed to), then can "click the deploy button" and have the automation do all the work.
Releases are grouped by "application", similar to a project in TeamCity. As a more advanced use case, you can use deployables. Deployables are essentially individual components of an application you include in a release; in your case the "Documentation" could be a deployable, and maybe contain an artifact of the .pdf and .docx files. Deployables from other applications (maybe a different team is responsible for them, or whatever) can then be referenced and "included" in a release, or you can reference ones from a past release.
Hopefully that provides some overview and fits your needs. Getting into this space is a bit overwhelming because there are so many terms, technologies, and methodologies, but my advice is to start simple and then slowly build upon it, e.g.:
deploy a single, manually uploaded component through BuildMaster to a share drive, then manually deploy it from there
add a deployment plan that imports the component
add a second plan and associate it with the 2nd stage that takes the uploaded artifact and deploys it to the target, bypassing the need for the share drive
add more deployment plans and associate them with pipeline stages and promote through them all to "close out" a release
add an agent and deploy to that instead of the default localhost server
add more components and segregate their deployment with deployables
add event listeners to email team members at points in the process
start adding approvals if you require gated "sign-offs"
and so on.
I did my build numbers as 1, and then 2.
Does this matter - is it just a mater of preference as to how you do them?
The Build Number (or CFBundleVersion) is not shown in the App Store so for the user it does not really matter.
The purpose of the Build Number is that developers can distinguish different builds using the same Version (CFBundleShortVersionString).
Consider you are working towards a version 2.1.0. Before you publish this version on the App Store, you probably want to distribute Beta builds to testers. If they report any issues and you fix them, you will need to create and upload a new build but probably still use the version 2.1.0. In that case you would use the Build Number to distinguish the two version.
You can use whatever you like as a build version. Apple provides a tool to increase the Build Number in Xcode projects named agvtool.
Another way (and what I personally do) is to use the git commit count as the Build Number. This can be automated via a Build Phase. That way, every change that you make (and commit) automatically increases your Build Number.
Is there a simple way to set the TFS Build Number to be an Assembly Version during build?
I've seen many examples of the other way around (i.e. a build number updates the assembly version).
We already use the SharedAssemblyInfo implementation from here, so we would like to leverage this setup during the build process.
Currently using TFS 2012 with Release Management template (ReleaseDefaultTemplate.11.1.xaml).
Without modifying the build process template? No. Even then, the build number is set prior to compilation (or, IIRC, even syncing the code from source control), so you're in for a wild ride trying to get the behavior you want.
There are multiple modules in our applications and each of them have their separate version and depend on other modules(external to our organization). They all have a parent POM which has it's own version, independent from the children's version.
When one of those modules change, they're converted to snapshots.
For the following example:
Parent v14.0
- module1 v1.5.0
- dependency1(module2 v15.0.0)
- dependency2(external-jar v12.0.1)
- module2 v15.0.0
- module3 v3.1.0
If there would be a change in module2, then module2's version would become v15.0-SNAPSHOT, then module1 becomes v1.5-SNAPSHOT. The parent remains the same.
The purpose for not having the same version on parent+modules, is that we want to localize the updates made to some modules and not affect the others' versions.
This has been designed like this a long time ago and there are several bash scripts to support the updates, although they're not handling all the cases. In any case, we don't have a one-click release process and we feel we are quite far from it with this approach.
We don't know how to convince the management towards a single version approach on all modules. How do you feel about the above? Did you ever encountered a project using the above structure and how well did it go?
Thank you!
I've had to deal with such situations before. There is an actual benefit from having decentralized versions, especially in cases where your product is made out of a large number of modules and this is because of the following facts:
You don't have to release all of them as a whole, if only a handful have been changed (which, from my observation is almost always the case).
You don't have to create unnecessary tags in your version control for code which hasn't changed since the previous release.
You don't have to waste an excessive amount of time releasing modules which don't need to be released.
You know with certainty which modules have changed in a release, which helps a lot when you need to investigate a complex bug, which seems to be dating back a while.
You can actually release certain modules/aggregators before the actual release date of the complete product, allowing for more testing time and a feeling of completeness for a given part of the product.
You can make feature branch releases much easier and implement a continuous delivery in a better way.
You can re-use the same code across multiple development branches without wondering if that branched version matches the one for your branch (or at least with less confusion).
What we ended up doing was:
Extract a parent or set of parents (with no sub-modules).
Try to use fixed versions for parents as much as possible. This is a bit of a caveat, as you must change all modules that inherit it, but in the end it improves the stability.
Extract each of the modules whose versions are independent of the rest to separate modules.
Extract sets of modules whose versions must always move along together into aggregators.
Create jobs in your CI server that can do releases or manually release these modules.
Use the versions-maven-plugin.
I think it's a lot more mature of a project and company's development principles to use decentralized versions and I must admit that in the beginning I was very reluctant to this approach. You might not realize or understand the benefits immediately, but with some practice and a proper setup, you will start seeing the upsides. I'm not saying there aren't caveats like... for example bumping the version of a parent, or having to know in which modules to bump the version of one of your modules.
From my experience, this module actually works better in the end, once you've become used to working with it.
From my experience: Everywhere we tried this, it eventually failed.
Although Maven supports this approach it is not advisable because of the additional effort.
I try to use the following criteria when choosing whether to use distinct projects or a multimodule structure:
If all projects have the same release cycle, I put them in a common multi module structure. In that case, I give them all the same version and release them together.
If a part of the project is used by different other projects (organizational projects), I always split them of and give them a separate lifecycle and a separate version.
If one part of my project stabilizes, I split it off, and give it a separate lifecycle (Maven refactoring)
To do it different alway results in homebrew solutions that neither scale well, nor are easy to maintain.
Hope that helps.
I want to make the builds on a specific branch advance the version number in AssemblyInfo.cs files and in Package.nuspec files according to the Semantic Versioning convention (*).
In order to do this, when code is merged into this specific branch, I want to:
Ask the merging user for a new version number, preferably during merge (then run build during check-in) or when the user runs a manual build, preferably displaying a custom dialog which displays current version number and asks if API has been broken, expanded or if changes do not affect API, then save the new version number aside.
Apply version number to AssemblyInfo.cs file(s). (Related link)
Apply version number to Package.nuspec file(s).
Run build.
Publish resulting NuGet packages.
I am not sure how to get the first step working, as it is interactive.
Has anyone tried such as approach before?
Are there any known solutions?
Any tips how to solve this?
(*) Semantic Versioning convention:
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.