It is very important to track the changes in every document of a project, in order for all the contributors to be in sync. In this article we will see how a few coding tools, like SVN, can be used to this end.
We’ll start with a description of the principles of version and configuration control. Then I’ll guide you through the installation and use of SVN applied to project document management.
We already talked about keeping track of a document’s changes in a previous article on it’s content organization. Microsoft Office changes tracking tools are rather useful in that way, if each user remembers to activate them.
However, it is quite rare to have only one document for a project. As we’ve seen, documents are linked together. A test document depends on a requirements document for example.
We also covered that when a document changes, other documents that depends on it must be updated. Indeed, if some changes need to be made in a requirements document finalized in revision V1, this document’s revision will be changed to V2. And as the test document in revision V1 was depending on the requirement’s document in V1, it must be updated to revision V2 to be compliant with the new revision of the requirement’s document.
This way we obtain 2 distinct configurations of documents. The first one refers to both documents in their V1 revisions, and the second one refers to both documents in their V2 revisions. Therefore, what we call configuration control is the tool that allows us to link different revisions of different documents together. And by extension it enables us to find a cohesive set of documents that work together at a given time of the project’s timeline.
Of course, all documents may not change between configurations. For example, some documentation about standards (ISO for example) may be part of the configuration, and only rarely change.
At the same time, some documents can appear in a configuration and not be present in the previous configurations. This can happen if, for example, one of the documents become more and more complicate and is divided into 2 separate documents for better maintainability.
| Configuration 1|
| Configuration 2|
5 documents (2 new documents)
| Configuration 3|
|Specifications V1||Specifications V2||Specifications V3|
|Functional specifications V1||Functional specifications V2||Functional specifications V3|
|Hardware specifications V1||Hardware specifications V2|
|Firmware specifications V1||Firmware specifications V2|
|Environmental standards V3||Environmental standards V3||Environmental standards V3|
Version number for documents may be (and almost always are) different from version number for the corresponding configuration. Configuration actually let us group together one revision of each document to “freeze” a consistent state of the project’s documentation.
Use of SVN for documentary version control
The internet is overflowing with document management systems (DMS or EDM) that you may already know. For large companies managing hundreds of thousands of documents, those tools are the right choice.
In this article, I will suggest a solution that can be set up quickly, and that integrates directly with Windows file explorer. A similar solution exist for Linux, and it would be my honor to present it to you if you ask for it.
This solution uses a piece of software well-known in the software development world a few years back : SVN (Apache Subversion in its full name).
For the attention of the software developers reading this, and asking themselves why they should use SVN and not Git, which is clearly more fashionable right now, I would say that popularity isn’t everything. The main benefit of Git over SVN, for developers, is that it is decentralized. That means, while obviously over-simplifying, that there is no need for an internet connection to use it. But this works well because the files handled by programmers are raw text, without formatting, easy to merge. Documentation files are often MSWord or PDFs that are almost impossible to merge automatically. We are going to have to lock files before editing them, and that is quite hard with a decentralized system like Git. End of digression!
SVN is a revision control system created in the early 2000’s to succeed to CVS. It’s a centralized system, that is to say that it runs in a client-server organization. Each client (user, document contributor…) holds on its computer the documents of the project, and those are synchronized with a server (like a directory in the cloud). Changes made by a user to a document are then committed (delivered) to the server in order for the other users to retrieve the new revision of the document. The SVN server behaves like a “source of truth” that allows every project contributors to share up-to-date documentation.
SVN installation and first commit
Nothing better than practice to understand how SVN can be used to share a set of documents and manage their revisions and configurations.
TortoiseSVN is a client software for SVN. It benefits from a very good integration to Windows file explorer. To clarify, SVN is a technology, a protocol for revision control, and TortoiseSVN is a piece of software allowing us to use SVN from our computer.
Let’s start by downloading TortoiseSVN last revision. You will find it there : https://tortoisesvn.net/downloads.html. As I write this article, revision 1.14.0 is the last one. Click on the button corresponding to your computer system (32 or 64 bits). Download should start.
Then execute the downloaded file (in my case it is named TortoiseSVN-22.214.171.124885-x64-svn-1.14.0.msi). Click “Next” to every step.
The TortoiseSVN tools should appear in the start menu of your computer :
And also in the context menu of the Windows file explorer (right-click in the explorer) :
Create a repository on RiouxSVN
You do remember that SVN follows a client-server architecture. You just installed the client software on your computer. It is time to create a repository on the server. What we call “repository” is the “source of truth” we talked about earlier.
For this tutorial we are going to use a free online SVN repository hosting service. Go to RiouxSVN and sign up.
Once that’s done, got to the repositories explorer https://riouxsvn.com/repositories/ and click on “Create new repository…”.
Give it a title and a name. There is no rule for choosing a title. The name must only contain lowercase and no spaces. I’m not the creator of RiouxSVN, don’t ask me the difference between a title and a name, I have no clue! But it won’t matter. Click on “Next step”.
On the next screen, check the “Create trunk, branches and tags directories” option. Click on “Next step”.
On this screen, you can subscribe to notifications from this repository. Each time a user makes a change to the repository, you will receive an e-mail. This may be useful in some case. You can change this behavior later if needed. Click on “Confirm creation” to finalize the repository creation.
The repository now appears in your list of repositories. Click on it’s title.
On this screen, you will find the URL of the repository you just created. Copy it (select it and Ctrl+C). You will need it at the next step.
Synchronize the server and the client
The last step in setting up SVN for this tutorial project is to use your TortoiseSVN client do link a directory on your computer to the repository hosted on RiouxSVN (the one you just created).
To this end, create a new directory for this project wherever you want on your computer. If you can’t decide, we have written an article that could help you. Then right-click on this directory and select “SVN Checkout”. A dialog box opens. that is where you should paste (Ctrl+V) the URL copied at the previous step. Then click on OK.
You will be asked to log in with your RiouxSVN account. Don’t forget to check the “Save authentication” option if you don’t want to re-enter your credentials at every operation. Click on OK.
A dialog box displays the executed transactions.
TortoiseSVN has copied into your directory the 3 sub-directories named “trunk”, “tags”, and “branches” present on the server repository. And you can notice there presence in the file explorer:
The .svn directory is a hidden directory. You may not see it in your file explorer. It’s OK.
The “trunk” directory is the main directory. It will be your workspace directory.
The “tags” directory is the directory in which you will find the different configurations we talked about at the beginning of this article.
The “branches” directory is found useful in more complex projects. We will leave it for today.
If you don’t see the little ticks on green circles, restart your computer. TortoiseSVN adds overlay icons in the file explorer to indicate the synchronization status of the different files and directories of the repository.
Save your first files
We often forget to talk about it, but one of the main assets of version control software is backup. Indeed, the files are all hosted on the server in order for all the clients to stay up to date. And as every change is saved, it is even possible to travel in time and recover the state of every file (or group of files) a any given (past) date and time.
Let’s imagine that you just received a specification document for this new project of yours. You just have to move it in the project directory.
Now you want to commit this new document, as well as the created sub-directory structure, to the server repository, so that the entire team has access to it. To that purpose, right-click on the trunk directory and then select “TortoiseSVN”, then click on “Add…”.
A dialog box opens to make us select the files and directories to add. By default, everything is checked. Leave it as it is.
Note that you cannot add a file or a directory if the parent directory is not added itself.
Click on OK.
Once again TortoiseSVN displays a dialog box to recap the executed transactions. Click on OK.
A big blue “+” has appeared on the directories and files you just added. And on the “truck” directory, the tick on a green circle transformed into an exclamation point on a red circle.
The big blue “+” means that SVN has taken into account the fact that for now on it needs to track changes made on those files and directories. However, as long as this “add” action is not synchronized nothing is updated on the server. And you can still cancel this “add” action for example (right-click -> TortoiseSVN -> Undo Add).
But the “trunk” directory, which was watched by SVN, now shows A big blue “+” has appeared on the directories and files you just added. And on the “truck” directory, the tick on a green circle transformed into an exclamation point on a red circle to make us aware that something changed somewhere in this directory, that is not yes synchronized with the repository on the server.
To actually save your changes to the server repository, right-click on the project directory, then “SVN Commit…”.
A dialog box opens to let us confirm the commit of your changes to the server. It displays a text field to leave a message, and a list of the elements to commit. If you did not already add your files and directories, you could have done it there, from this dialog box.
I strongly advise to leave a message saying why you commit a new revision of the files. Although it’s not mandatory, it’s a priceless help for you and the members of your team. Being able to remember why we made these changes is of great assistance. Take advantage of this!
Click on OK.
Once more, TortoiseSVN displays a dialog box to recap the executed transactions. For example, the “Commit to https://svn.riouxsvn.com/naept_demo” line indicates that the changes made are sent to the server.
Click on OK.
Every TortoiseSVN icon overlays turn green. Everything is synced with the server. It’s a little like a backup. Your computer could freeze, burn, what do I know? You can always retrieve what is committed to the server.
Update your local copy
Let’s pretend that a colleague of yours started writing some software specifications for this project. He then committed his changes to the repository, and because you subscribed to notifications for this repository, you received an email to inform you about this change.
However, your local project directory is not automatically updated. You have to do it manually. So it’s a good habit to do this update before making any change on your side.
To update your local copy, right-click on the project directory, then on “SVN Update”.
As always, TortoiseSVN displays a dialog box to recap the executed transactions.
If no change had been made since your last update, this list would obviously be empty.
What would have happened if you had started working on a file before updating your local copy?
Well, during update, TortoiseSVN would have alerted us with a conflict notice! Nothing bad actually. You would just have had to choose between 2 revisions of the file: yours or your colleague’s one. We all know which one you would have chosen, but your poor colleague would have worked for nothing…
A good habit to adopt for this kind of event is to always lock a file before working on it. This way the other members of the team won’t be able to edit the document as long as you’re not finished with your changes.
A second good habit to have is to always commit an empty file just after creating it. To “save a spot” in a way. Some conflicts can be avoided doing this.
To lock a file, right-click on it and select “TortoiseSVN, then click on “Get lock…”.
A dialog box opens to allow us to confirm the files you want to lock. You could have locked many files by right-clicking on a directory rather than a file. Don’t forget to let a message to your colleagues to let them know who locked the file, and why.
The usual dialog box informs us that the lock is in place.
The lock will automatically be removed by SVN during the next commit involving this file. You could also do it manually, if you change your mind about working on this file for example. To do this, right-click on the file and select “TortoiseSVN, then click on “Release lock…”.
Freeze a configuration
Now that the whole team agrees on saying that all the documents of the project are finalized and work well together, it is time to create the aforementioned configuration.
By convention, configurations are placed into the “tags” directory. To put it simply, a configuration is a copy of the trunk directory at a given time.
Right-click on the “trunk” directory (not the project directory), then select “TortoiseSVN, and finally click on “Branch/tag…”
The dialog box that opens is to create a branch or a tag. Here is how to fill in the form to make a new tag.
The “To path” field must contain “tags/” followed by the name you want to give to this new configuration. This name is free, but must follow the directory naming rules (talking about forbidden characters for examples). For the rest, just agree on some rules with the team and stick to it.
As for committing, add a message describing the changes made since the last configuration revision. Don’t be cheap on words and explanations.
Leave the other fields as is.
Oh! Maybe I did not tell you about this dialog box that recaps the executed transactions? Well you notice that it is actually a copy that SVN made to create a tag.
Now if you navigate to the “tags” directory, you will find a new directory that has the name that you chose for this configuration. It is possible that you need to update your local copy (as seen previously) to have a “tags” directory up to date.
If you need to send project files to a client or anyone outside the company or outside project, just pick them in this configuration directory. This will ensure that they are mature and coherent.
That’s it for this introduction to configuration control on documents with SVN. We could go a bit further but maybe in an other article if you ask for it. This first approach should be enough to handle most of the projects.
For more on revision control, I direct you to the TortoiseSVN documentation which is really good, and available in many languages: https://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-basics.html
What about you?
What piece of software do you use to manage your documents?
What good practices are in place in your teams?
Do not hesitate to share and comment this article.
Have a nice day!