Using SVN to Manage XForms

SVN is a tool that allows a large number of people to all maintain the same version of their documents, and helps assist with merging in changes and keeping logs of old versions of those documents. Using SVN to keep track of XForms makes sure that implementers and developers alike can make sure everyone is using the expected version of forms for each deployment.

Installing SVN

There are a number of different clients for using SVN. If you will be doing any active development of the JavaRosa code, you should probably focus on setting up the development environment instead at the [wiki:GettingStarted Getting Started] wiki page instead.

'''Software to Download'''

• [http://tortoisesvn.net/downloads Tortoise SVN]

Once you've installed Tortoise SVN on your system, it will appear on the Context Menus that appear when you right click in the empty space of a folder in Windows Explorer. From here you can get access to the SVN Commands you'll need. Once you have files checked out from SVN, the file icons will appear with small icons on them signifying their status. You can also right click these files to access file specific (rather than folder specific) commands. Don't worry too much about what these commands are just yet, but make sure that when you right click in Windows Explorer you get two new options: "SVN Checkout" and a submenu "Tortoise SVN".

SVN Overview

We can now cover a very brief introduction to using the basic SVN commands you'll need to manage documents, and how to access them using the Tortoise SVN application. There are many other features of SVN that you can use once you become comfortable with the system. If you find a good tutorial of them, please add it to this section of the Wiki.

The essential model of SVN is that you maintain a 'checkout' of a set of files on your local system, which you can '''Update''' to make sure you have the latest versions of those files, and '''Commit''' your changes to in order to make them available to others.

Checkout

To start, you'll need to create a Checkout of a set of files on the SVN Repository, which is the central svn server. A checkout will create a set of files on your system which you can then change and push those changes back, or keep up to date.

'''Tortoise Checkout'''

• In windows explorer, right click on the empty space inside of the folder you want to store your documents in.
• Select 'SVN Checkout'
• In URL of repository, enter the URL of the folder on the server where the XForms are stored (Instructions on figuring out what this folder is follow).
• Click 'OK'

Depending on the server (This doesn't apply to standard JavaRosa servers), you may be prompted for a username and password. If you don't have one, contact a JavaRosa developer to gain access. If you do have one, just enter when prompted.

What is the URL for My XForms?

This question depends on your project. You can ask a developer on your JavaRosa application if you aren't sure. The URL for the demo project's xforms is

• http://code.javarosa.org/svn/trunk/j2merosa/org.javarosa.demo/resources/ There are a few things that can help in finding the URL you're looking for. You should be able to put it in the address bar for a web browser, and see a list of the files you're looking for. You can also explore the repository using a browser in this manner.

Update

Once files are checked out on your local system, SVN will allow you to keep them up to date using the update command. Update looks at the server, and identifies whether there has been changes to those files since you last updated, it will then take those changes and merge them into your local files, keeping you up to date. If an update can't intelligently merge in changes from outside, a Conflict occurs, which will be discussed later.

'''Tortoise Update'''

• In windows explorer, find the file or folder you'd like to update, and right click.
• Select SVN Update

Commit

SVN Commit is the command you'll use to put your changes on the server, so that people can update their repositories and get your changes. You should commit changes as often as possible, after ensuring that they still work by using the validator. Committing often makes sure that everyone can enjoy your changes, and ensures that no one gets too far out of sync with the other team members.

'''Tortoise Commit'''

• Perform an SVN Update as instructed above
• Verify that your changes work by running the XForms validator on the form
• In windows explorer, find the file or folder you'd like to commit your changes for, and right click.
• Select SVN Commit
• You will be presented with a list of files that have been changed in some way since being checked out. Any files that have a checkmark next to them will be commuted to the server, any that do not have such marks will not. Make sure that the list of files has the appropriate markings (Checkmarks for any file you want to commit your changes to)
• Click Ok

'''Note:''' In Tanzania, avoid committing changes when you're using SimbaNET internet. We've seen weird problems where your computer thinks the changes went though, but the changes never actually went through, and everything ends up in an inconsistent state that's a royal pain to fix. If you need to use SimbaNET to commit, do so as a last resort, and immediately verify afterward that your changes actually went through (go to http://code.dimagi.com/CommCare/log/trunk, see your change listed at the top, AND click the number in brackets (the Chgset column) and verify that your specific changes are shown!). SimbaNET is known to be used in the Pathfinder back offices.

Add

SVN can only perform Update and Commit actions on files that it knows exist. If you create a new file, it has to be '''Added''' to the repository before you can commit changes to it or anyone can obtain it. Tortoise will generally do the legwork for you of identifying that you've added a new file to SVN, but you'll need to make sure that you're committing changes to the '''''folder''''', and not the file for that to work. Additionally, they will not appear unless you have clicked the 'Show unversioned files' box in the lower left hand corner of the commit dialog.

If you want to, or if SVN doesn't seem to be seeing your file, you can add files manually.

'''Tortoise Add'''

• In windows explorer, find the file or folder you'd like to add to svn, and right click it
• Select Tortoise SVN -> Add...
• Click Ok
• Perform an SVN Commit using the instructons above

SVN Conflicts

Section Coming Soon