Site Search
Homepage of Otaku No Zoku
Complete Archives of Otaku No Zoku
About Otaku No Zoku
Subscribe to Otaku No Zoku
Bookmark Otaku No Zoku

A Dozen Rules for Effective Version Control :

If you develop software either professionally or as a hobby using a modern version control package is a no brainer.

Even if you only work on hobby projects by yourself and nobody else ever gets to touch the source code or binary assets there is little excuse to not use version control for your projects. It doesn’t matter what version control package you happen to use, using the package effectively is universal issue.

Hopefully these guidelines that I’ve adopted over the past few decades, most of them learned through bitter experience rather than any useful guide or manual, will enhance your effective usage of version control. Never again be afraid to change a piece of code to test out an idea or worry about “losing the source code” years after you have worked on something.

  1. Never check-in anything at the end of the day.
    1. Ever.
    2. This rule is the Golden Rule.
    3. It is inviolable.
    4. You will completely regret having checked in last thing the previous night if you do.
  2. Check-in often.
    1. Don’t go weeks (or even days) between check-ins.
    2. Create a cheap branch to allow you to check-in without breaking the build.
    3. If you aren’t comfortable with branches, create temporary directories in the version control.
  3. Synchronize regularly.
    1. Synchronize.
    2. Synchronize.
    3. Synchronize.
  4. Your check-in procedure should be:
    1. Compile (if you cannot compile, why are you trying to check in?)
    2. Synchronize.
    3. Compile (if you cannot compile after synchronization, why are you trying to check in?)
    4. Check-in.
    5. Synchronize.
    6. Compile (if you cannot compile after all that, you have a merge error.)
    7. Run your unit tests or run the executable, whichever it is you do. (“It compiles, let’s ship it” is not a mantra for the development of robust software.)
    8. This will generally prevent about 99% of screw ups.
    9. It takes an extra minute or two.
  5. Build all platforms and configurations.
    1. Xoreax IncrediBuild works great for this. So do other distributed build systems.
    2. Make it your job to have the time necessary.
  6. Other programmers will thank you for not breaking their configuration or platform.
    1. The continuous integration server/build monkey is not a crutch for bad habits.
    2. Bad habits make the build monkey angry.
    3. Don’t use the build monkey to catch your compiler errors.
    4. An angry build monkey is not something you want to deal with.
  7. Don’t check-in then go for lunch, coffee, smoke, bathroom break, nap, etc.
    1. Wait for the automated e-mail from the continuous integration server/build monkey to be sent out to verify all is good in build land.
    2. You do have a continuous integration server/build monkey? Right?
  8. Don’t edit files without checking them out.
    1. Not even for “quick fixes.”
    2. If you are going to be editing a file to test something out, and just want to “try it”, check out the file to a new change list with the description “DO NOT CHECK-IN.”
    3. That way, if you do something stupid, you can easily tell which file you did the stupid thing in by performing a diff.
    4. You can instantly see how your source code differs from the one in version control.
    5. And if you find you do want to commit your changes, it is easy to determine which files you modified with your “quick fix.”
  9. Atomize your commits.
    1. Each one should be a discrete step in the development process that reproduces perfectly a singular change.
    2. Don’t check out dozens of files, complete a half-dozen tasks in your project plan then commit them all back in.
    3. Break it up.
    4. Commits are cheap.
    5. Mistakes aren’t.
  10. Don’t work outside of the version control directories.
  11. Configure your continuous integration server/build monkey to compile after every commit.
  12. If you think it should be in version control, put it there.You can always take it back out later.

Bonus Rule!

  1. See rule #1.

Liked This Post?

Subscribe to the RSS feed or follow me on Twitter to stay up to date!