Revision Control

Prompted by an excellent article – Subversion for writers – I thought it might be useful to offer a Windows view. Like most software groups, our development team use a version control system to manage multiple versions of the product; we have customers using many previous versions and all are maintained in the same system so we can patch fixes back through multiple versions.

Our team of writers use the same system, although as we are using FrameMaker we lose some of the nicer features but the core reasons for using a version control system remain – files are locked by whoever is working on them, and we have a full version history of changes made, including when, who and why.

We use Subversion which, when I joined the company, I’d had no experience with. However the basic premise is simple, you store the master files in a central repository and everyone uses a client to manage a local working copy (updating and locking the central repository as required). TortoiseSVN is our client of choice, which offers a simple right-click menu to access the required functionality. One advantage of this system is simplicity as it is a file-based, single lock system, so only one person can work on a file at a time, ideal for most technical writing teams.

Presuming your files are already in the central repository (there are many guides on how to do this, it is very straightforward) you first need to create an empty folder on your own machine, this will be the local working area. You then checkout a copy of the master files from the central repository to your local working area. The checkout process will mimic the folder structure used in the central repository, and Tortoise will now start to apply rules to those folders (more on that in a bit).

It’s important to note that once you have checked out files locally, they are still under version control. To delete or add files to this local area, you will need to use the options available through Tortoise (right-click a folder or file in that area). Files and folders under version control will have an additional icon to indicate their current status.

To work on a file (or files) you must first lock it in the central repository, then open it in your preferred editor. If there is a newer version of the file in the central repository, you will be prompted to update your local copy first. Once the file is locked you can edit it as normal and when you are finished and have saved the changes, simply close the file, right-click and select Commit. The changes you’ve made are updated back in the central repository and the file is unlocked for others to use.

We currently use FrameMaker and it works fairly well with this system, although there are some limitations. As the file format FrameMaker (or Word for that matter) uses isn’t binary, then you can’t use various commands so no merging of documents, for example. However if you need to maintain multiple versions of the same document it works well.

There are a couple of gotchas though, and we use a combination of SVN (Subversion) locking and the CheckFileStatus plugin for FrameMaker to get a process that works for us.

The plugin simply flags whether the file you are opening is read-only or not, and as SVN locking simply sets that property on the selected file, it’s enough to catch whether you are trying to work on a file that hasn’t been locked. In other words, all the files in your local working area are read-only until you lock them and remove that property. Once locked the files are no longer read-only and the plugin will allow you to open them to work on.

It does mean that you need to set an SVN property on the files you have checked out which will mean you CANNOT edit any files until you have requested a lock from SVN. This way only one person can edit a file at a time, which suits our needs (as we cannot use the ‘merge’ functionality in SVN).

To add the property:

1. In your local checkout directory, right-click a folder, and select Properties.
2. On the Subversion tab, click Properties.
3. Click Add… .
4. Enter the property name (you’ll need to type it) “svn:needs-lock”.
5. Enter a property value of *.
6. Select Apply property recursively.
7. Click OK, then OK again.
8. Close the Properties dialog.

Note: SVN doesn’t actually apply this setting to the folder, just the files within it.

And that’s it, you are ready to go. To work on a file, or set of files (like a FrameMaker book and chapters), select them in your local working area, right-click and select Get Lock… . Once locked, you work with the files as normal and once you are done, right-click and select SVN Commit… .

Done. Hope this was helpful.