In your Documents folder do you have a Final-Report-V1, Final-Report-vFinal, Final-Report-vFinal-Johns-comments, etc.? How about the experience of having worked on a software assignment all night long, only to have something, somewhere cause a crash minutes before it is due?

Then you have seen a glimpse of the importance of version control to your company, and more importantly, to your career.

The Importance

As a student, backups and constantly saving files was a personal CYA, and unless you were working on a team, a lost file only hurt you. You also had the generous benefit that when the term was done, you could burn, delete, kill, or otherwise maim any document you had spent so much time on and have no repercussions.

Now, as the professional you, there is much more at stake when a file goes missing or bugs creep in at the last moment.

While there is a large amount of personal CYA that benefits of good use of version control, the company has a legal and financial obligation to keep good records and backups of the work created by you and your team.

Product and business decisions may need documented reasons to satisfy auditors and heads may literally roll if the next release is delayed due to an undocumented change.

What Version Control Is, and Is Not

Version control is a software tool or procedure that is designed to track changes to a file and allow a user to backtrack changes to specific revision when needed.

The details of implementation vary, but the idea is that every change is logged and could be reverted.

Version control should not be viewed as a hard drive, as it’s not meant to store everything in your documents folder. An example is the build output of your software, which lives on your hard drive, and not in version control.

The rule of thumb of what should be stored is the minimal  documents required to recreate the output. Things such as external libraries should not be stored, but rather fetched by software scripts to download from their source.

Best Practices

There are a number of easy ways to protect yourself and your company by using version control to its full potential.

Before going into my own experience, the best place to start is seeing if your company has a version control procedure. If not, maybe by the end of reading this you could write one up that fits the tools your company uses and submit it up the chain – perhaps even earning yourself a nice kudos along the way.

1. Find the right tool for the problem.

Git has become the dominating tool for software development, but it is not so helpful for binary files such as CAD, Office documents, or images.

Some applications such as SolidWorks have built in tools (at an additional cost of course) but are specifically designed for the file contents. Microsoft Office 365 has some version control available, but for many other files, a documented convention on a shared drive may be the only option.

Do a bit of digging to find the right tool for your application, even if that means multiple tools for large projects.

2. Research the conventions for the tool.

Tools such as Git have their own dialect and conventions that, while easy to copy and paste commands, they are not always intuitive until you understand the inner workings.

Managing versions on SolidWorks has a different convention and use case that are equally important to understand.

As with any tool or software the more you understand the ins and outs, the faster and easier it is to use. So spend some time up front learning about the tool and its best practices.

3. If the current solution works, don’t fix it.

Imagine a shared server drive that has sub-folders named current and archive, where the convention is that before you make changes, save the current file into the archive, update the filename revision, and edit away.

Clunky and ugly?

Oh, yeah, but sometimes this is all the more that is needed, and trying to force a change will only cause more headaches.

As engineers, especially as fresh engineers, we are often hot to try the newest things and find ‘old’ practices, well, old. The procedure may be terrible and outdated, but if it works you must find good justification to initiate the change – and it better be a good reason because change is hard and expensive for companies.

4. Commit incremental changes.

When modifying a project, be it code or CAD drawings, make sure you are committing multiple, incremental changes along the way – not just the big at-the-end-of-the-day commit.

This has bit me more than once when I have been hacking away getting one thing working, move onto the next and find that I broke the first. If I had saved a version in between, I could have reverted to a previous change and moved forward until something broke.

Instead, I spent a great deal of time backtracking all the changes and tried to remember what I did earlier.

Save often, commit often. But…

5. Only commit what works.

As a contradiction to number 4 above, you should only commit something that is ‘working.’ If it is software, it should compile, CAD drawings should render, and documents should have completed sentences.

This is especially true if multiple people are working on the project, you do not want to be the one who is blamed for breaking the build.

‘Working’ doesn’t have to mean complete. You maybe be adding complex features to a project that will require many changes. So instead of waiting until it is completed, stub out new features, add incremental changes, verify it builds, and commit.

Finding a balance can be tough, but well worth the effort when something breaks.

6. Use branches.

If your software tool allows branches, this would allow exceptions to number 5.

Branches are a way to take the current version of a project and create a copy of it. You could then do anything you want here such as experiment with a new idea or commit every line of code change.

If the changes you made are needed back in the main line, then the tools will allow a way to ‘merge’ you changes back in. If they don’t work out, you can toss the branch without hurting anything.

The other benefit of branches is that anyone can check out the master, or trunk, and know it is stable – all new development is in the branches.

7. Make the best use of commit messages.

Most tools allow you to make comments when you commit changes.

What is not needed is for you to list the files and line numbers, the tool should do that for you. Instead, make notes of why you changed something, bug/case numbers that relate to the change, and notes for how to test the new changes.

When someone goes back through your change log, they should be able to understand why you made the decisions you did without needing to corner you in the lunchroom.

This also comes back to point number 4: Commit Often, by splitting changes into small commits, it is much easier to document and follow the changes.

8. Preach it, but do not force it.

If your office does not use revision control, it may not be wise to attempt to force it upon your co-workers.

They may have their own systems they like and are used to and do not always take kindly to new ideas. Instead, demonstrate the usefulness that you are getting out of it and the benefits to the company.

Tools like Git don’t require external servers or cost any money so you could easily set it up on your machine and demonstrate to your coworkers how it has been helping you and offer to set it up for them.

Your Challenge

So now I’ve hopefully got you fired up for why version control is so important, and the basics of how you can implement it within your company.

Now that you have learned it, now make it.

Your challenge is to implement version control within your workflow or improve your process by studying the tools and procedures used by your team.

If you have a great story of version control or want to share how you helped your team implement it, hit up the comments below and share with the community.