Team Collaboration Using Subversion (SVN)
- Daily Use
Once your project has been set up, these are the steps you will use on a daily basis:
- Edit the project
- Merge changes from other team members
- Resolve any conflicts (usually, there aren't any)
- Commit your changes
1. Edit the project
In general, you are free to edit your GUI Design projects as if you were the only user. You can create files and folders, delete them, rename them, move them and, of course, edit their content.
This is in contrast to other Check Out / Check In type version control systems you might be familiar with, where you can only modify files that you have locked for editing.
Important Note: Both GUI Design Studio and Subversion need to keep track of all files that have been added, deleted, moved or renamed so you must perform these operations from within GUI Design Studio and not from Windows Explorer or your SVN Client.
As you make changes to files, the icons in the Project tree will change. Anything that you've added or modified will be displayed with a red tick instead of a green one (you might need to Refresh the tree to see this in some cases):
While the freedom to edit any file gives you ultimate flexibility as an individual designer, and allows you to be disconnected from the central server while you make changes, you do need to be aware of the price for this flexibility and the consequences of your actions.
Subversion is extremely good at merging changes from different users. But there are times when conflicts occur and only a Human (i.e. You!) can sort it out (see Step 3 below).
So it works best when each designer in the team is given a particular area of responsibility with the provision that they can make editorial changes (fixes) to designs in other areas, or changes that integrate their own areas. Otherwise, the design experience will feel somewhat chaotic and you'll spend too much time resolving conflicts.
2. Merge changes from other team members
Before you commit your changes to the repository, you must first incorporate any changes that have already been committed by other team members. You can also do this at any time that you want to incorporate those changes, whether or not you are ready to commit your own changes.
Make sure that you save all of your own files to disk first using the "File | Save All" menu command (or toolbar button) in GUI Design Studio then issue an SVN Update command from your SVN client. You will nearly always want to do this on the top-level folder of your project.
If you're using TortoiseSVN then you can simply right-click the folder from Windows Explorer and select the "SVN Update" command from the context menu.
In this example, you can see that:
- a new "Admin Edit Property.gui" design file has been added
- the "Admin Login.gui" design file has been updated (there were no local changes)
- the "Web Real Estate.gcat" project file has been successfully and automatically merged
- the repository is now at revision number 5!
If you want to, you can view the log file to see the change comments made by your colleagues.
Back in GUI Design Studio, you can use the "Refresh" button on the Project panel to update the file tree and see all of the changes.
3. Resolve any conflicts
Most of the time, the Update process should complete without a hitch and you can jump straight to the Commit step.
But, sooner or later, you'll get a conflict and you'll have to resolve it before you can commit your changes to the repository:
Resolving (.gui) design file conflicts
Unfortunately, there is no way at the moment to visually compare the conflicting changes in a graphical manner. Your SVN Client's Merge tool will normally present the files in text form and ask you to choose which conflicting lines should be used.
Try to think of the textual view as an alternative property editor. It should all be point and click to select the changes to keep so you won't actually be typing text to edit the file.
With TortoiseSVN, double clicking the conflicted file in the Update report will open the merge tool. Click on the Next/Previous Conflict buttons to display them:
Since each design element property appears on its own line, the conflicts should be minimal and it should be fairly easy to decide which version to use in most cases. Your version, their version and the original version of all the lines are displayed for comparison.
Right-click the block you want to choose and select the appropriate option in the context menu:
Once you have selected the lines to keep for each conflict, mark the file as resolved then close the merge tool:
You don't have to resolve conflicts immediately. You can open the Merge tool from Windows Explorer at any time. If files are left unresolved, a 'Conflict' icon will be shown in the GUI Design Studio Project tree:
Where conflicts can get tricky is when a Window or other container element has been moved by more than one user. In that case, all contained elements will also appear to have moved and this will result in a lot of conflicts. The thing to do here is decide whose changes to keep (yours or theirs) and be consistent in every related conflict.
TIP: In a multi-user environment, avoid moving top-level windows and containers around the canvas on a stotyboard-type design unless absolutely necessary to make space for something else.
Resolving (.gcat) catalogue file conflicts
These can sometimes occur when two people add files to a project and the file records happen to be inserted into the .gcat file at the same place. In this case, Subversion can't determine whether it is two insertions or two versions of the same insertion, so it's flagged as a conflict for you to sort out.
In every case, simply use the option to "Use text block from 'theirs' before 'mine'" (it may be called something different in your merge tool). Don't worry if this does not result in quite the right order.
If you are about to commit your changes then you should open your copy of the project in GUI Design Studio (if it's not already open) and perform a "File | Save All" operation first. This will re-sort the catalogue file to ensure that further updates go more smoothly.
TIP: The more files there are in the project, the less likely a .gcat conflict will occur. So, at the start of the project, try to add a number of files before introducing a second team member or let one team member create the project structure in the early stages (using blank placeholder designs).
4. Commit your changes
Now that your Working Copy is up-to-date with everyone elses changes and you've resolved any conflicts, it's time to commit your changes.
With TortoiseSVN, right-click the folder again from Windows Explorer and select the "SVN Commit..." command from the context menu to open the Commit dialog:
Enter a useful and descriptive message to help you and your colleagues understand what you've done then click the "OK" button to complete the process:
Note: If someone else has committed further changes since your last Update then the operation will fail and you'll have to go through the 'Update -> Resolve Conflicts -> Commit' cycle again.