5 Revision Control Best Practices

Every embedded software developer should be using a revision control system. I cannot even begin to quantify how much time I’ve saved using such systems through-out my career. When something has broken, and cannot be undone, the ability to roll back to the previous version is a life saver. Even as developers recognize and use a revision control system, there are several best practices that they should use in order ensure that their revision control system is fully utilized.

Best Practice #1 – Exclude the Debug folder

The debug folder contains all the object files, binaries and executable files that are generated by the compiler for the source project. While a team may want to save release versions of these files, keeping them in the revision control system has several disadvantages:
• Object and executable files tend to be large and can quickly use up a lot of space in the revision control system
• When checking out a revision, developers should build using their own toolchains and not be dependent upon files that could have been compiled under different conditions
• Files that have not changed could be in a different state and cause unexpected behavior when the software is executed
For these reasons and others, developers should avoid saving the debug folder and its contents in the revision control system.

Best Practice #2 – Use the “ignore” feature

Most revision control systems such as git or mercurial include the ability to ignore certain files and file types. A great way to use this feature is to create an ignore entry for objects, executables and other files that the repository system should ignore and not add into the repository. The exact method on how to ignore file types will vary from one revision control system to the next. The best approach is to consult the user manual.

Best Practice #3 – Submit detailed commit logs

One of my biggest pet peeves is when developers commit code to a repository and either put no comments or so few comments that it’s impossible to determine what actually changed in the code base. Having a detailed list about the code and what changed is critical to being able to roll back and find previous versions when they are needed. Countless times something in software breaks and developers need to review the logs and determine when that feature was added or modified. Without a detailed log, this process becomes a time-consuming nightmare. There are key pieces of information that should be included in every log:
• The software version number
• What was added to the software and where was it added
• What was modified in the software and which modules were affected
• A list containing all currently known outstanding issues with the software version
• Any general comments that would be beneficial

Best Practice #4 – Synchronize often

Revision control systems are only useful if the developers using them synchronize their software base often. Going days or weeks without committing code is looking for disaster to strike. The same issue can occur if a developer doesn’t pull the latest changes often enough. Their software can quickly get out of synchronization with the rest of the code base. For that reason, developers need to make sure that the synchronize often. If they don’t, they may find themselves spending far too much time trying to merge their code into the master branch.

Best Practice #5 – Tag / Branch official releases

When there is a code base that is going to be released into the wild, separate that code by branching or tagging it as an official release. Keeping this code separate will make it far easier for developers to go back and find the code release. Code that is tagged or branched as an official release should also not be touched or modified in any way but kept as a pristine copy.

Conclusions

Following these several best practices will help ensure that you are not just using a revision control system but that you are getting the most from that system. A revision control system can save time and effort if it is used properly. These best practices will help ensure that you get the most from your system.