D.1 Understanding Subversion

Subversion is a version control system. Version control systems let you manage and create multiple revisions of your project and documents. They also allow you to share those revisions among a team of people.

D.1.1 How Revisions Work In Subversion

Revisions are a the heart of the Subversion functionality. A revision is a number that marks a specific set of changes made to a set of files. A single revision number can cover changes made to multiple files, but all of those files must be in the same repository.

Subversion uses a single revision number for the entire repository. This revision number is incremented every time any change is made to the Subversion server. For example, if you import a project at revision 100 and then create an Identity Vault and commit (revision 101), create a driver and commit (revision 102), and create a policy and commit, you are at revision 103. If you have multiple projects in the same repository, every change made to any project increments the revision number for the whole server.

Although revision numbers are created for the entire server, different objects in your project can have different revision numbers. For example, suppose you start with revision 100 and create a policy and commit it; then create a mapping table resource and commit that version. The project will be at revision 100, the policy will be at revision 101, and the mapping table resource will be at revision 102. You can see the current revision of a specific object by using the Revision History or Properties page. The Revision History page indicates the specific object revision with a yellow arrow. In this example, the yellow arrow points to revision 100 for the project even though you see revision 101 and 102.

Subversion is meant to work in a team environment. In a team environment, there could be someone else editing the project at the same time as you. Let's look at an example:

  • Alice imports a project at revision 100 to her local workspace.

  • Bob imports the same project, also at revision 100, to his local workspace.

  • Alice adds a new policy and commits, which creates revision 101.

  • Bob adds a different new policy and commits, which creates revision 102

At this point Alice’s project is at revision 100, her policy is at revision 101, and the latest revision on the server is revision 102. If Alice wants to see Bob’s policy, she needs to update her project so she has revision 102.

Figure D-1 Viewing Changes Through the Revision History

Revisions are a useful way to track the versions of your project. Revisions can help you get projects back from the history and make sure that two users have the same version of a project loaded.

D.1.2 Understanding Atomic Commits

Atomic commits are a major feature of Subversion. The atomic commits treat the commit operation as a single event that either completely succeeds or fails gracefully. That means all of your changes are committed to the server or none of them are. For example, Alice and Bob are working together on a project. Alice makes changes to multiple policies and entitlements that are all interdependent. While Alice is in the process of committing this change, her network connection goes down. Before Alice can connect to the server again, Bob does an update. Subversion ensures that Bob does not get a partial update from Alice. Because Alice had a problem during her commit, Subversion makes sure that none of the files are changed on the server. Alice can then perform the commit after her network connection is restored.

Atomic commits are a very powerful tool and an excellent way to avoid broken projects. Atomic commits are always available within Identity Manager Designer and Subversion. You don't need to do anything special to enable them.

D.1.3 Where Subversion Stores the Project Data

When you commit a project to Subversion, the project is stored in the Subversion repository. The Subversion repository is an based on an internal database Subversion uses to store files. Subversion stores a separate file containing the specific changes made in each revision using the revision number as the filename.

These files are combined to maintain the concatenation of all of the changes made in your repository and the history of those changes. These files are iterative in nature and contain only the changes made for that specific revision. You can access these files in the db/revs directory of your Subversion repository.

Beyond that one requirement, there are no firm rules about setting up your projects. Here are some guidelines:

  • It is a good practice to place a project in a directory of the same name. For example, a project called project1 would go into a folder such as trunk/projects/project1.

  • Most repositories have a “sandbox” area. Users new to version control can experiment in this area without worrying about corrupting existing projects.

  • It is a good practice to organize groups of projects. You can group projects by user, team, or company. The key is that having a large number of projects at the same level can be difficult to navigate.

D.1.4 Moving an Existing Project

Identity Manager Designer does not provide support for moving a committed project from one place on your Subversion server to another. However, you can do this with the Subversion command line:

  • Make sure the whole team commits all of their local changes.

  • Have all team members delete their local projects.

  • Use the Subversion move command to move the project location.

  • Have each team member import the project from the new location.

The Subversion move command is very simple. You just specify the current location of the project and the new location you want to move it to. For example, if your project is located at trunk/project1 and you want to move it to trunk/myprojects/project1, use the following command:

svn mv -m "<your comment for the move>" http://myserver/trunk/project1 http://myserver/trunk/myprojects/project1

Subversion moves the project to the new location and maintains all of the files and history.