Using the Chorus Synchronization Dialog

Chorus is an open-source version control porcelain (over Mercurial plumbing) designed to enable workflows appropriate for typical language development teams who are geographically distributed.  Chorus is designed to be integrated into other applications, and installed with their installers.  This blog is the first of several in which I will describe what an application developer needs to do to incorporate Chorus.  It is not logically the first thing I should write about, but there are a couple projects which already have the more basic stuff worked out, so I’ve decided to just start with the next thing they need.  Someday, I’ll go back and blog about some previous steps to incorporating Chorus into your application.  Note that for now, you need to use a .net language to use Chorus. If there is demand, it will be simple matter to provide the most important functionality via the command line, so that non-.net apps can use Chorus as well.  Chorus works with mono, so you can use this on linux as well.

The easiest way to start a synchronization job is to use Chorus’ new “SyncDialog”.  Using this, you give the user feedback and offer some control over the process. You don’t have to use it, but it will improve over time at little cost to you, and it is designed to be customizable for your needs. It is also available as a Control, so you can embed it in some other view, if you don’t want the whole dialog.

Using Chorus for Backup

One common use of Chorus will be for performing automated backup.  This is a big issue in many Language Software applications, because the user often

1. possesses relatively low computer-skills
2. in environmental conditions which are hard on computer hardware (dust, sea-spray, humidity, lightning)
3. subject to high theft rates, particularly of expensive, light-weight things like netbooks

So automated backup is  a great thing to build into your applications.  Simply by “checking in” to the local version control in the folder holding your application’s documents, you provide a full history of the project so that it is possible to roll-back to a previous state.  By adding a secondary media backup location, like an SD card, you decrease the chance that a hardware failure will result in loss of work. 

For this kind of synchronization, which we’ll call “backup”, you just want to assure the user that it is happening and let them know if something went wrong.  You could do this in various ways which are less intrusive than a dialog box.  But if you do use the SyncDialog to do it, you’ll want to keep it pretty minimal. For example, when WeSay does its automated backup, it invokes the dialog like this:

var dlg = new SyncDialog(configuration,
       SyncUIDialogBehaviors.StartImmediatelyAndCloseWhenFinished,
       SyncUIFeatures.Minimal);

dlg.Text = "Wesay Automatic Backup";
dlg.SyncOptions.DoMergeWithOthers = false;
dlg.SyncOptions.DoPullFromOthers = false;
dlg.SyncOptions.DoPushToLocalSources = true;

 Which gives us:

 

When the backup is over, the user sees the following for about a second, and then the box closes.

(Note, I’ll describe the “configuration” parameter above in a separate post.  It basically tells Chorus what file types you want checked in.  Also not described in this post is how you can tell the Chorus Synchronizer whether you’re interested in pulling from other sources, or just pushing to them, as in the case of backup).

Using Chorus For Synchronization

Whereas backup should be totally automated, there are other times when its appropriate to give the user full control. For example, when an advanced user clicks “Send/Receive” in your application, you may want to give the user the chance to clarify which devices/people/servers he’s planning to synchronize with, view the steps Chorus is taking to locate, pull, merge, and push back to remote servers, etc.  To simply bring up a dialog box with all the controls the dialog has to offer, we use code like this:

var dlg = new SyncDialog(configuration,

                    SyncUIDialogBehaviors.Lazy,

                    SyncUIFeatures.Everything))

 

Which gives us:

 

 

When you click the Send/Receive button, it switches you to the log tab:

And if there is a problem, it plays an error sound and displays a warning icon:

If you click the “Show diagnostic information” box, you get exhaustive details on everything Chorus and Mercurial are saying to each other :

 

Some applications, like WeSay, need to allow the administrator to lock things down a bit, so that the user doesn’t uncheck the team repository and then forget to ever check it again.  To do that, instead of the everything flag, we might limit it to just one tasks tab (not shown), plus a confirmation sound. For example, we might say:

 var dlg = newSyncDialog(configuration,

        SyncUIDialogBehaviors.Lazy,

        SyncUIFeatures.PlaySoundIfSuccessful | SyncUIFeatures.TaskList))

Which would leave out the “choose repositories” and “log” tabs, and instead show the (not yet implemented) tasks tab (see below).

Flags

At the time of this posting, here are the compete set of  flags you can tailor its startup/close down behavior.

public enum SyncUIDialogBehaviors
{
    Lazy=0,
    StartImmediately,
    StartImmediatelyAndCloseWhenFinished
} ;

[Flags]
public enum SyncUIFeatures
{
    Minimal =0,
    SendReceiveButton=2,
    TaskList=4,
    Log = 8,
    RepositoryChooser = 16,
    PlaySoundIfSuccessful = 32,
    Everything = 0xFFFF
}

TODO

• Add the tasks tab, which shows you an outline of the tasks that will be attempted and the status of each one (similar to the dialog in MS Outlook).
• The cancel button currently doesn’t have the ability to kill a long-running mercurial operation (I’m a bit scared of doing it). So the cancellation only happens in-between steps chorus itself is taking.
• Nothing in Chorus is internationalized yet.
• The progress bar is just one of those “I’m alive” ones at this point… it has no idea how much progress has been made.