Software Best Practices: Version Control
A few days ago, at the start of my work day, my laptop refused to boot up. Having just got off the road my first relieved thought was "glad I am not at a customer site." My second, more worried, was "when was the last time I synced my work in the repository?"(1)
Within MathWorks Consulting we use SVN for version control, and on client projects I have worked with GIT, CVS, Rationale Clear Case, and many others.
The one thing they all have in common is that they are only as good as the processes in place behind them.
Lets address a common misunderstanding about version control software; it is not a file back up system. While it performs the functions of a file back system the objective of version control software is to manage versions of software in a collaborative development environment(2). In other words it is a tool intended for team based development for projects that evolve through multiple stages.
(Original image XKCD (5))
There are two primary types of version control software, Centralized (like SVN) and Distributed (like GIT). The mechanics of the system differ their are core best practices that they share.
- Check your artifacts in regularly: When working in a collaborative environment the longer you go without checking in your changes the harder any required merges will be.
- Validate your changes before check-in: Version control software makes it easy to check things in without verifying the objects impact on the full system. Remember even if it works in your local copy it does not mean that it will work in your current branch of repository. (however it is more likely to work if you are following best practice #1)
- Create intermediate release points: Stable, intermediate, release pints give you the ability to revert changes easily. Note a stable release is not the same as a fully functional release; it simply means that the models perform a subset of the full functionality without errors.
- Include meaningful comments: A meaningful comment provides both what and why a change was made. If the change is in response to a bug than include a bug tracking number; if it is based on a requirement, provide the requirement link.(4)
- Talk to your co-workers: Good comments do not take away from the need for talking and coordinating with your co-workers. Many a difficult merger can be avoided by a single simple conversation.
Model Based Design architectural best practices to simplify merging
Within Simulink the recommended method for decomposing models is through Model Reference Blocks. These blocks enforce a locked down interface from which the system level model can be created. The recommended best practice is first create a system level model composed of "shell" referenced models. The shell model specifies the function interface, number of inputs, outputs, data type and dimensions of the block.
Individual users (Susan and Bob in the image above) are assigned one or more "shell" model to elaborate with content. As long as they do not change the model interface they know their model can be integrated into the system without issues. If they need to change the model interface they work with the system integrator to propagate the required change to other engineers.
Notes:
1.) My first thought when my laptop died was thinking of version control as a back up system. It was that incorrect thought that prompted me to write this post.
2.) While collaboration is an important concept for version control software it is useful even on projects worked on by a single developer. The ability to create and merge branches permit the developer to safely try out new development concepts.
3.) There is a bonus video post from Friday Nov 4th. Enjoy!
4.) If you have thoughts on this post, please feel free to leave a meaningful comment
5.) The link is for the 3%(6) of the software and engineering world who did not recognize the comic style.
6.) The figure of 3% was derived through a Fermi estimate
BIO
Michael Burke is a consultant with The MathWorks and former coordinator for the MathWorks Automotive Advisory Board (MAAB). I currently focus on Model-Based Design Process Adoption and Establishment projects. Views expressed in this article do not represent the views of The MathWorks.
Principal Application Engineer at MathWorks
7 年I definitely agree that version control is not a backup method, although it can certainly assist with backup methods. On my previous projects, the process was to check code into the version control system, and the entire version control system would have regular backups that would be stored off-site. This method assisted with computer failures as well as catastrophic incidents, such as destruction of the building. As part of the backup process, a restore procedure was periodically tested to ensure the backups were viable. There would be a several month rotation of the off-site backups, with the intent of minimizing losses should a set of backups somehow become unusable, while also trying to maintain a reasonable amount of off-site storage.
Exploring the landscape of AI Validation
7 年Hi Jamie, That wasn't the analogy that I was thinking of but it works fairly well. I normally think of Model Reference blocks like function definitions in C in that they number and types of I/O but don't define any methods.
Technology Fellow at Allegro MicroSystems. Passionate innovator, mentor, husband, father and student.
7 年Thanks for the post Michael. So my understanding is that Model Reference can be used the same was as a Java class that implements an interface.