Every file/script/resource needed to build your product is stored in a version control system. Most shops expect this coverage to apply to source code, but it also applies to graphics, build scripts, installer files, configuration scripts, database schemas, library version information, and so forth. Anything needed to build and ship your product needs to be versioned so that changes are understood, and previous versions can be resurrected as needed.
- Shipping code can only be built on a single machine
- It’s difficult, or impossible, to build old versions of your product
- Significant work is lost when hard drives fail, power blinks, or malware strikes
- Product resources are stored on network drives and overwritten with new, or just different, versions
- The product fails an audit because there’s no history for a signifant portion of the shipping files
- Bugs in production can’t be located in local source code trees
- The team has to contact graphic artists to locate copies of graphics
- Build scripts only live on a single machine
- Database can’t be recreated using only information in version control
- Environments can’t be recreated because of missing information about the (database, environment, app server configurations, …)
- Every historical version of the product can be built whenever they’re needed
- Accessing historical versions of the product to support customers is trivial
- Product breaks can be tracked to specific changes and understood
- Minimal work is lost when local changes are wiped out
- You have a persistent, shared memory about every change to every file
- Build scripts aren’t lost when the build machine dies
- Collateral (graphics, html, and so on), and the associated history, is always available
- Staging new environments requires much less time
- When “that co-worker” breaks things, you understand what happened
✓ Critical ❑ Helpful ❑ Experimental
- Set up a version control instance on another box (anywhere but your local machine)
- Install a version control client on your local machine
- Check in a copy of your local source (with all known collateral)
- Move to a new environment (or to virtual machine) and try to build the product using only what you get from version control
- Set up a continuous integration machine
- Make notes about what’s missing. Track down those items and check them in.
- Repeat until you have a list of tools needed in a clean environment, and everything else is in version control
What Does it Look like?
Good version control exists when you can create a scripted build that doesn’t need anything on your machine other than the compiler, a version control client, (and perhaps a scripting tool or two). No network shares, images, build scripts, etc. Everything needed can be pulled from your version control system and built, all with a single command.
Think of version control as something like an insurance policy. When you are buying an insurance policy, you might ask questions such as how easy is to file a claim, can I get true replacement value to replace anything that’s missing or damaged, and how expensive is it to carry this insurance?
This is in addition to all of your project work. Don’t just version the source code, but all the scripts you use to build, test, or deploy your work. Add additional product resources, like html or images. What about icons? Anything that you spend time creating should be versioned.
- You sit down to do some work and update your copy to the latest version
- As soon as you finish one thing, you check it in. Check in the smallest amount of working code possible.
- Repeat all day
When you check in a set of changes, you need to enter a meaningful comment. Do not just say what changed, but explain why. The “what” will be taken care of by the version control system itself.
Here are some key questions to ask to get feedback about your use of version control:
- Is it easy to use day to day, minute by minute, all day long?
- If any file is damaged or missing, can you replace it quickly and completely?
- Is it easy for you to experiment, and wantonly wreck files all over the place, and use version control as an UNDO button?
- Can you look at the logs and understand why changes were made?
The answer to all of these questions should be yes, of course. If not, then you’ll need to fix your version control system and/or your use of it.
- Your version control is slow and difficult to use
- Your version control tool has no command line
- People constantly require access to version control experts to be able to use the system
- Your version control tool requires a support contract to function properly
- Code checkin intervals are measured in days or weeks
- You can’t build your product without a very specific version of a tool (open source or not) and you don’t have a copy versioned
- You have more branches than developers
- Large numbers of branches insulate team members from each other’s changes. Be sure you’re not using them this way
Exercises to Get Better
- Practice checking smaller and smaller slices of code. You’ll likely move to slices that are too small. Then find a good balance where you’re sharing small, but working, slices of code on a frequent basis.
- Review your code checkin comments. Are they meaningful? Understandable? Can a teammate understand your intention without also reading the code change?
- Check your version control status every day and see what pending changes you’re leaving on the box overnight. How much work do you lose if the office catches fire or your desktop is accidentally wiped by the IT staff?
How to Teach This Practice
- Spend time pairing with new team members. This practice is easily observed and understood when seen. Spend time working together with new additions to your team and help them catch the culture.
- Check your version control logs at the end of the day. Anyone who hasn’t checked in code can be ceremonially mocked. Silly hats, unwashed shirts, or stuffed animals adorning one’s desk area, or an obligatory song, are all good responses.
How To Fail Spectacularly
- Checking in code less frequently because things break when the code is checked in (delaying the problem only makes it worse)
- Checking in each line of code as it’s changed
- Allowing every developer to work on their own branch for months at a time
- Allowing feature branches to exist in isolation for months at a time
- Using a file share or email as a “version control” system.
- Using zip files of project trees and email clients as “version control”
- Using version control, but allowing “experts” to edit code directly in production because it’s faster
- Holding all your edits until 30 minutes before the end of the iteration
- Writing your own version control. An awesomely bad idea that leads to fractal debugging. As in the movie Inception.
Actual quote: “The problem with version control is frequent check ins. That’s when everything breaks. If everyone would just hold onto their changes for a few months, then we’d only break everything once, not every day.”
This quote came from a developer who held his changes for several months, then broke the system when he’d merge his changes into the system. Small frequent check-ins were working fine for the rest of his team.
(Continuous Integration) Next→