10 Version Control Guidelines
Version control is a must-know for developers, even beginners. In this re-post, I discuss the 10 guidelines for using source control properly
(Revised original post from March 2, 2010)
Using version control is vital to a development shop. It doesn't matter whether you work solo or with a team of developers. Managing code is a necessity and a required skill for developers.
Even though I'm one developer, I used to have a subversion server in my basement. If I wrote a piece of bad code, I knew I could rollback the code to a previous version instead of trying to wrack my brain figuring out what code to back out.
In a team or corporate environment, though, you may have some developers who are new to the team and unfamiliar with version control software like GitHub, Azure DevOps, CVS, or Subversion.
These guidelines are definitely required for any new or seasoned developer.
- DO NOT break the build
If you learn anything from these guidelines, it is this: DO NOT CHECK IN CODE THAT WILL BREAK THE BUILD! If a person breaks the build and a new version is scheduled for release, it can't be done because the code isn't in a stable state for release. It's truly amazing that one person can bring an entire team (and project) to it's knees.
- DO NOT commit code before doing an update or "get latest."
Developers who are new to version control systems may not understand updating before checking/committing code. They want to immediately check their code in before they lose it. The down side is occurs when numerous developers commit code on a file you are working on. When you commit without updating, you are basically overwriting their changes when you check-in. This may make 1+ developers pretty upset with you. If you continue to break this guideline, you may have to look for another job at that point.
- DO incremental check-ins
After you finish writing code (and your unit tests pass), check in your code to version control. When you frequently check in your code, this gives you the ability to refactor with confidence because if you mess something up, you can easily revert back to an old version.
- DO implement a continuous integration server
When you check code in, the continuous integration server immediately compiles and builds the project. If there is an error, an email is sent out to the user who last checked the code in and they are notified that THEY have broken the build. Usually, the process involved giving the culprit a item of shame to let others know that they broke the build.
- DO use a merging tool
When there is a conflict in the project code, have a solid understanding of not only how to merge code from one source file to another, but understand the true potential of how each merging tool functions.
- DO tag and tag in moderation
When a project build is at a stage where everything is stable according to the lead developer and project/product manager, make sure all code is checked in, builds, then freeze the code, and attach a tag with a version number to mark the checkpoints of your project. It's much easier to rollback to a tagged version of the product instead of guessing where the change was made.
- DO minimize the duration and amount of branches
In a large team of developers, multiple groups may break off into numerous feature branches. Unless you have a version control guru, merging these issues can be a nightmare. The more branches you have, the worse it will be to merge the changes into the trunk. If you shorten the duration (day/week/month) of the branches and have a small amount of branches in the project, the merging will be less of a nightmare.
- DO commit changes daily
If someone hits the lottery (the bus scenario is too gruesome) and leaves the company or if someone is sick for a day or two, you forgot to have your latest code committed. While you're out sick and a deadline looms, guess what? Someone else may go through code and notice yours in missing and start fixing/coding your part that's already done. You know how this will end so I'll just say commit your changes daily.
- DO run tests on code
Every time code is pulled from the code repository without a tag attached to it, there should be quality assurance tests executed against that build. This confirms that the code is stable enough to release into the testing or production environment.
- DO commit assets and all related material
This is geared more towards designers, DBAs, and project managers along with developers. Commit all of your assets including graphics, documentation (like One-Sheets), specifications, DML statements, SQL data, and other additional materials. Once committed and tagged, you'll be able to sleep better at nights.
Conclusion
I consider these guidelines to be the basics for knowing how to use source control, whether it's VSTS/Azure DevOps or GitHub.
I know there are other rules, but based on previous experiences, these were the most common version control guidelines I could think for developers who wanted to know the basics.
Did I miss any guidelines? What would you tell a beginning developer learning source control? Post your comments below and let's discuss.
