As you know, embedded software changes at a dramatic rate. How we manage software version information dramatically affects whether we can successfully understand the differences between those versions. Several years ago, I wrote a blog entitled 5 Tips for Versioning Embedded Systems. Today’s post will explore a few tips for versioning embedded software.
Tip #1 – Use a standard Git process
Over the years, I’ve seen just about every version control process ranging from the hope and pray your computer doesn’t crash method to clearly defined Git processes. Before developing a successful versioning scheme, it’s essential to follow a robust Git process. For example, recently, I’ve come across several companies that only work out of their Master branch, which was causing a lot of problems with multiple developers. A standard process can help alleviate issues and improve visibility in the repository.
A Git process that I’ve found to be simple, robust, and easy to implement is the process written about in A Successful Git Branching Model written by Vincent Driessen. The overall process can be seen in Figure 1 (and I highly recommend reviewing the blog post). There are undoubtedly other processes, but I’ve found this one the simplest and easiest to get buy-in.
Figure 1 – A Successful Git Branching Model demonstrates how to manage various branches, including feature, develop, releases, hotfixes, and master. (Image Source)
Tip #2 – Only version release branches
In the “old days,” every time a software module was updated, a new version number would be assigned to the code. Changing the version number was meant to indicate that the software had changed. However, for many teams, versioning software every time a change has been made doesn’t make sense. The time between software changes is dramatically getting shorter and shorter. It’s not uncommon to commit new code a dozen times or more per hour.
The best place to version software is in the release branch of the Git repository. While features are in development, it doesn’t make sense to increment the version number continuously! Instead, features should be fully developed and fleshed out before being added to a release of the software. This gives developers the freedom to focus on rapid feature development without worrying about how they are going to version their software. It’s only versioned when the team is ready to release a new version or a hotfix.
Tip #3 – Don’t add version and date info to individual modules
Diligently tracking the changes made to software has always been important to developers. Early in my career, it was drilled into me how important this was and that this information should be tracked down to the individual function! It was not uncommon to find comment blocks in my code that looked the following:
/*************** MODULE REVISION LOG *
* Date Version Author Description
* 09/01/15 0.5.0 Jacob Beningo Interface Created.
* 11/10/15 1.0.0 Jacob Beningo Interface released.
****************************************************/
Or at the function level like:
/***************************************************
* Function : Dio_Init()
- * – HISTORY OF CHANGES –
* Date Software Version Initials Change
* 09/01/2015 0.5.0 JWB Interface Created
* 11/10/2015 1.0.0 JWB Added const to parameters
*****************************************************************************/
While the code looks nicely documented, I’ve found that this versioning has several problems. First, module and function level versioning is difficult to synchronize with the overall application versioning. So, the version numbers often don’t match or correlate properly. Second, versioning at this level can confuse developers. Third, putting versioning information all over the place makes it hard to find what changed and when. Finally, due to other reasons, I found this version information rarely gets updated, making it a waste of space and providing essentially no value to the code base.
Tip #4 – Add version history comments to the README
The most logical place to store version history information is not at the module or function level but in the README file. When I get a new code base, one of the first places I go is a README. If the version information is there, it’s one of the first things I look at to get a feel for what has recently changed and how the software evolved.
Another place where version information can be stored is in a version.h or version.c module. There are several reasons why I am not the biggest fan of putting changelogs here. First, version.h often contains autogenerated version information that is used by the application. We don’t want our log information to be a file that can be overwritten or where we must overly complicate a script to preserve our comments. Second, storing the information in version.c, while convenient, is creating a source module that has no actual code in it.
Tip #5 – Use a script to update your software version
There are three types of version updates that are typically applied to a codebase:
- Major version release
- Minor version release
- Hotfix version release
It’s okay to manually update these releases because we are typically manually branching to the release branch anyways; However, I have found that this process can be simplified and less error-prone if a script is used instead.
Several things can be done with a versioning script. First, you can update the version of your code by having the script automatically update and generate a file like version.h. Second, you can even automate the branching and tagging process in your Git repository. Finally, you can write a script that combines it all.
Conclusions
Embedded software versioning isn’t rocket science, but to do it effectively, you need to take a few moments to define your process. As discussed in Tip #1, using a repository process can help you manage your software quickly, whether you have 1 or 1,000 developers. Once you have this process down, versioning is as simple as using a script to set your version and then managing your releases and tags appropriately.
