Version Control

Every file, script, resource, or asset needed to build your product is stored in a version control system. Most people expect this coverage to apply to source code, but it also applies to graphics, build scripts, installer files, configuration scripts, database schema, library version information, containers, build pipeline scripts and so forth. This can also include diagrams that describe the architecture and what boxes this code might run on should others need to perform future maintenance. Anything needed to build, maintain, and ship your product needs to be versioned so that changes are understood, and previous versions can be resurrected as needed.

Pain Points

• Shipping code relies on network assets that suddenly disappear¹
• Shipping code can only be built on a single machine
• It’s difficult, or impossible, to build previous 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 different versions
• The product fails an audit because there’s no history for a significant 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
• Databases can’t be recreated using only the information in version control
• Environments can’t be recreated because of missing information about the database, environment, application server configurations, etc.

Benefits

• Every historical version of the product can be built whenever needed
• Accessing historical versions of the product to support customers is trivial
• Defects 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 things break, you understand what happened and can recover

Assessment

Application

✓ Critical ❑ Helpful ❑ Experimental

Adoption Experiment

What Does it Look like?

Think of version control as an insurance policy. When you buy 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?

Good version control exists when you can create a scripted build that doesn’t need anything on your machine other than the compiler and related tools, 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.

All your scripts, tools, and customizations should be kept under version control. Using git? Then your .gitconfig is in version control. Using bash (on macOS or Linux?)? How about your .bashrc and/or .bash_profile? Did you alias sl to ls? How about mroe to more? What about a batch file called ls.bat? What about your tooling preferences? All these things are in your version control system.

For the project itself, don’t just version the source code, but all the scripts you use to build, test, and deploy your work. Add additional product resources, such as HTML or images. What about icons? What about network assets? Anything that you spend time creating, any project asset, should be versioned.

• You sit down to do some work and update your copy to the latest version (e.g., git pull or svn up, etc.)
• 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:

1. Is it easy to use day to day, minute by minute, all day long?
2. If any file is damaged or missing, can you replace it quickly and completely?
3. Is it easy for you to experiment, and wantonly wreck files all over the place, and use version control as an UNDO button?
4. Can you look at the logs and understand why changes were made?

The answer to all of these questions should be yes. If not, then you’ll need to fix your version control system and/or your use of it.

Warning Signs

• 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 check-in 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 in 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 check-in 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 your 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 habit

• Spend time pairing with new team members. This habit is easily observed and understood when seen. Spend time working together with new team members and help them catch the culture.

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.
• Working with an extensively customized environment, investing hours or days into getting it all just the way you like it, then watching it go away with a hard drive failure
• Pushing files that contain your own IDE preferences to the team repository and overwriting everyone else’s customizations

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. See also ContinuousIntegration.

  ←Prev (Create Team Agreements)(Continuous Integration) Next→

---

Find Out More...

Follow @growsmethod in the Fediverse, or subscribe to our mailing list:

Sign up for more information on how you can participate and use the GROWS Method®. We will not use your email for any other purpose.