rmurphey

Getting non-developers on the subversion bandwagon

Posted

Marcus turned me on to subversion when I was working on a project earlier this year and wanted a way to revisit old versions of files. Setting up a subversion repository was easy, and while I did download the Tortoise GUI for Windows, I found the command line was pretty easy too. A few months later, we were wrestling at work with an issue I've confronted at every job I've had: how to maintain a filesystem that ...

• allows everyone to have access to any file they might need
• promotes the concept that files are associated with a client, not with a person
• facilitates regular and thorough backups
• provides versioning more sophisticated than multiple files with names like project_outline_rev2.html
• does all this without intimidating the hell out of people who aren't on good terms with the command line

It wasn't a typical use for subversion, which is more normally (in my mind) used for version control with straight-up development projects, but the more I thought about it and talked about it with people who had used subversion, the more it seemed to make sense. We'd be using it to manage an infinite number of concurrent projects related to maintaining a large client's web content, and that meant we'd have to agree on a directory structure beyond the standard branches/tags/trunk. For it to work at all, I was also going to have to convince people -- some of whom were scarred by cvs -- to actually use it. I braced for a full-fledged campaign: sure, it's more complex than no system at all, I would argue, but writing HTML is more complex than writing in Notepad, too, and we seem to handle that OK, right? As it turned out, my campaign lasted all of a day, and wasn't much of a campaign at all. One designer suggested using Dreamweaver or VersionCue to address these concerns, to which I said:

one of the things i like about subversion (svn) is that it's a platform/software agnostic tool. if we used dw for site management, everyone would have to use dw -- for the homepage update i just did, i hardly touched dreamweaver, preferring to do most everything in vim/command line because it was just so much easier for the sort of work i was doing. i know that at least on the pc side, there is a subversion extension for dreamweaver. i also know on the pc side there's a pretty decent gui svn client. i imagine, since macs are getting pretty popular with devs, that there's something similar on that side. i don't mean to shoot down dw/vc out of hand, but i think that it would introduce some real limitations vs svn, even though it is tempting because it is a tool we already use. another thing that is great about svn is that it's integrated with the whole trac system that stancil has set up, which also includes a wiki and a ticketing system, all of which are linked together. i see *huge* potential here in terms of project management, documentation, and file management that we aren't taking advantage of, and that wouldn't be available with a dw solution. ... it's possible that we don't need svn for everything, but honestly i think it's easy enough to use once you get the hang of it that it would be just as easy as the fileserver approach, with a ton of added benefits. perhaps the only true drawback is the disk space that would be required for versioning psd's and such. but disk space is cheap, and it think the extra storage we'd need would be worth its small cost if we had constant access to everything.

Our sysadmin already had some repositories set up that weren't getting wide use, so setting up another one was trivial. He added a bunch of disk space in anticipation of the new storage demands (while subversion just stores diffs for text files, it stores full copies of each binary file, and we were going to have a lot of those), and I wrote up some instructions for getting people started:

Download and install the subversion binaries

• for mac (click the download button)
• for pc (choose the latest .exe file)

Download the GUI

• scplugin for mac
• TortoiseSVN for pc

Mac folk: update your path to include svn

• open terminal
• cd ~
• pico .bash_profile
• enter the following:

  PATH="/usr/local/bin:/usr/local/subversion/bin:$PATH"
  export PATH

• press CTRL-O to save
• restart terminal

Establish ssl certification

• open a Terminal window (mac) or Start > Run > cmd.exe (windows)
• type svn ls https://www.svnserver.com/repository/trunk/ and hit enter (get the exact URL for your repository; this is just an example)
• enter user/password
  • if your username on your machine is the same as your svn username, enter your password.
  • otherwise, press enter and you'll be prompted for your svn username. enter it.
  • enter your svn password.

Getting started and basic workflow

I sat down with a group of initial users to do the initial checkout of the repository and show them the basic workflow. TortoiseSVN makes things especially easy, while scplugin is a bit more rudimentary. Here's the workflow I explained:

• update a folder before you begin work in it; to save time, just update the specific folder, not the whole repo
• make your changes
• add any new folders and files you create to the repo -- they won't be added automatically!
• if you change the structure of a dir, or remove a file, you have to do it via svn!
• rename to change a file name or move a file
• delete to remove a file
• update folder prior to commit to receive others' changes
• commit (check in) whenever you reach a milestone or stop work. enter a message with your commit to indicate what you did.

File structure

Subversion is usually used for managing development projects, but we wanted us to use it to manage an infinite number of small, concurrent projects related to our work maintaining the content on a large client's web site. The branches/tags/trunk paradigm didn't quite fit here. We ended up keeping the b/t/t setup, but most people just check out the trunk, which contains the following folders:

• client_site, with a directory structure that mirrors the structure of our client's web site. This is where we keep most of our files. By mirroring the directory structure of the client's web site, we make it easy to find a file if we know the URL of the file on the site.
• projects, for files related to projects that don't fit neatly into the site structure.
• resources, for image templates, HTML templates, fonts, logos, etc.

To do

Because we are constantly creating new files and adding them to the repository, some directories are getting unduly large, making updates take a long time, and forcing users to store a lot of unnecessary files locally once they do an update. We need to work out a way to age files so they are still available and easy to locate, but don't get picked up as part of the update process.

Further reading

• Basic Work Cycle