A List Apart

Menu

I Wonder What This Button Does

Issue № 220

I Wonder What This Button Does

by Published in Project Management, Workflow & Tools42 Comments

The instantaneous reaction to screwing up a piece of a project is, generally, denial. That file wasn’t actually deleted, was it? Changing the configuration didn’t really break the application, did it?

It was. And it did.

Let’s skip right over anger, bargaining, and depression, shall we? You messed up, and your previously exciting weekend is now looking more and more like a frantic struggle to make everything work again before anyone notices.

Problem? What problem?

Happily, there are solid technical solutions for avoiding this sort of mistake. A revision control system like Subversion provides the ability to wrap up all the files associated with a project and manage the changes made over time. In essence, Subversion can act like a time machine, zipping you back to that sublime moment just before you ruined your Saturday.

Even better, you aren’t the only one that Subversion helps. Your whole team can use Subversion in order to moderate the everyday disasters that occur when more than one person tries to work on a project at the same time. Bob and Alice both edited coolNewThing.html? No problem! If they edited distinct pieces, Subversion can automatically merge the changes. If their edits overlap, Subversion notifies them of the exact points of conflict (and, importantly, whose code they’re in conflict with) so that Bob and Alice can sit down together to resolve the issue instead of scratching their heads when their hard work simply disappears.

So how does this work?

Surprisingly little of your workflow needs to change when moving to a revision controlled environment. The process boils down to four basic steps:

  1. Make sure you’re working with the most recent version of the project.
  2. Do some work.
  3. Test your work (and fix the bugs you introduced).
  4. Tell everyone else about your changes when you’re satisfied.

You were presumably doing all of these things already. Revision control just makes it easy.

Keeping up to date

In a team environment, it’s dangerous to work with project files that have been sitting on your computer for a while. Other people are working just as hard as you are, and their changes are eventually going to overlap with something you’re about to start playing with. Inevitably, you’ll overwrite someone else’s work, or they’ll overwrite yours. The unbelievably widespread practice of e-mailing zip files around is marginally effective, but it’s an inefficient, cumbersome, and error-prone workaround.

Subversion solves this problem by creating a centralized storage location, called a repository, that acts as the team’s shared source for project data. By managing your project within a repository, you can keep track of all the important changes to all the files you’re interested in.

When I’m ready to start working, I first ask Subversion to make sure that all my files are up to date (as you might expect, Subversion calls this process an update). It compares my working copy with the latest revision of the project in the repository. If any of my files are out of date (or have been accidentally deleted), they’re automatically brought into line with the latest and greatest.

Once I’ve updated my working copy, I know that I’ve got all the important changes up till now, and I can start working without fear of accidentally overwriting someone else’s work.

Doing work

Sorry, Subversion can’t help you here. Much like the homework-doing robots I always dreamed of as a child, the coding-for-you revision control system is still a couple of years off. That said, Subversion does facilitate experimentation and creative freedom, as you’ve always got a “safe” copy to revert to if your experiment fails miserably.

Testing your work

Subversion can’t tell you whether your code works, but it can be a handy resource if you find that your code doesn’t work, or worse, breaks something that worked yesterday.

You’ve got a complete record of all the important changes to your files right there at your fingertips, so you can very easily “diff” your (broken) working copy against the (functional) previous version to see exactly what lines of code you changed. Seeing what’s changed is stunningly useful for diagnosing any issues you’ve inadvertently created, as you’ve narrowed the problem down to a very specific subset of the total project.

Distributing your work to your team

When you’ve completed a chunk of work, you need to make sure it gets recorded as an important change in the repository and is thereby shared with your team. This process, known as a commit, merges the changes you’ve made to your working copy with the repository, ensuring both that everyone else on the team has access to them, and that the code is safely stored somewhere other than your disaster-prone desktop.

Importantly, Subversion doesn’t just capture the changes from revision to revision; it also captures context by allowing you to enter free-form notes along with your committed changes. Rather than just dumping a few new files into the repository and sending out an explanatory e-mail that will be forgotten as soon as it’s read, you can record the content of those changes directly in the repository. When Bob’s got questions or accidentally creates a conflict with Alice’s revision, he can just check her change log and see that she:

  • Added a snazzy sidebar to `coolNewThing.html` and modified style rules in `coolNewThing.css` to support it.
  • Changed the default link colour to periwinkle blue, per customer request.

This is critical information, and it’s kept right there with the files where it can do the most good. Embedded context is light-years better than a forgotten e-mail, and is reason enough to implement Subversion.

Next steps

Obtaining Subversion is a trivial process. Just grab the distribution appropriate for your operating system and install it. This will load the client and server utilities onto your machine.

Setting up and maintaining a “real” networked Subversion server for a group is beyond the scope of this article; it’s really a task for your friendly sysadmin or IT department. That said, many web hosting services provide Subversion repositories as part of your hosting package, and there are a few excellent companies that specialize in hosting repositories.

For a quick taste, I’d highly suggest looking at O’Reilly’s excellent (and Free) Version Control with Subversion, which has a stellar Quick Start that walks through the process of creating a locally hosted repository, and interacting with it. This walkthrough covers about 80% of your interaction with Subversion, and is well worth the read (and purchase, for that matter).

Additional resources

If you’re already comfortable with the command line, you’ll be pleasantly surprised at how simple it is to integrate Subversion into your everyday work. If not, there are a number of brilliant GUIs that make Subversion a breeze for those disinclined to pop open Terminal and type svn up every morning and svn commit every few hours:

  • RapidSVN is a cross-platform Subversion GUI that wraps up pretty much everything you’ll need into a fairly well laid-out interface.
  • Eschewing a traditional GUI, TortoiseSVN directly integrates with Windows Explorer, offering an intuitive, file-based mechanism for keeping your project up to date.
  • Many text editors and IDEs can directly interact with Subversion: Xcode, TextMate, BBEdit, Visual Studio, and Eclipse are the tip of the iceberg, check your favourite!

Finally, there’s a lot that Subversion can do for you that I haven’t mentioned yet. Branching, tagging, post-commit hooks, and other useful features are described in detail in the book I mentioned earlier: Version Control with Subversion. It’s a comprehensive look at what Subversion does, how it works, and best practices for it’s use in your projects.

About the Author

42 Reader Comments

Load Comments