Worklight Studio provides some interesting challenges when it comes to source code management.  Getting just the right files checked in takes a bit of planning, and getting it right the first time makes a big difference in how smoothly the overall process will go.   The goal is to check in only those files that won't be modified/generated when the application is built.  This both saves storage space in your SCM system, and reduces the number of commits needed to keep your workspace in synch with the repository.

All the information here is based on tests with Worklight Studio 5.0.5 in Eclipse Juno running on OSX.

Why not CVS?

CVS isn't the most brilliant SCM system, but it is an old standby for simple SCM with Eclipse.  It is the one team provider that is packaged with base Eclipse.  Unfortunately, there is a long standing Eclipse bug that  results in conflicts when a Worklight Project that is checked into CVS is rebuilt.  Eclipse CVS ignores the .cvsignore file when CVS metadata is present in a directory, and the Worklight Build process results in the CVS metadata from some source directories getting copied into generated directories.

As simple and convenient as CVS is, trying to use it with Worklight projects will just lead to tears.

Using Subversion

Probably the easiest next choice for SCM is Subversion.  There are 2 leading Subversion team providers for Eclipse: Subversive and Subclipse.  Subversive is a bit easier to set up, and can be completely installed via the Eclipse Marketplace.  Subclipse is also available in the Eclipse Marketplace, but by default it depends on an external library (JavaHL) that must be installed manually.  On OSX, this means installing MacPorts or Homebrew, and using those to build the library.  Subclipse can easily be configured to run without JavaHL, but the default configuration will fail if JavaHL isn't installed.

Unfortunately, I had several problems using Subversive with Worklight projects.  It had to be explicitly told to check in some files, and it failed completely with a larger, more complex project.  In the end, I took the jump and switched to Subclipse.  In addition to succeeding where Subversive failed, it seems to perform much better for the initial check-in of a dojo project. (which is quite time consuming in any case.)

When you install Subclipse through the Marketplace, you are presented with the option to install both the Subversion JavaHL Native Library Adapter, and the SVNKit Client Adapter.  The later is the pure Java solution and is marked as optional in the feature list.  Interestingly, JavaHL is not marked optional, though it is.

You can install either or both client adapters.  If you install both, the default configuration that you will get in a new Workspace is to use JavaHL.  If you don't have the JavaHL libraries installed, this will fail.  You will need to go to Eclipse - > Preferences -> Team -> SVN -> SVN Interface and select SVNKit.  While workable, this is a bit annoying, so if you don't intend to use JavaHL, the easiest thing to do is to just not install the JavaHL adapter when you install Subclipse.

This is not meant to be a general primer on Subversion.  I'm still finding my way around it myself.  But when using Subversion (or any SCM system) with Worklight projects, a little bit of planning goes a long way.

The key is to _not_ check in files that will be regenerated during the Worklight build and deploy.  If this is done right, checking out a project and simply building and testing it should not result in deltas from the repository.  The Worklight Infocenter has some notes in this area.  

Unfortunately, there isn't a way to add files and folders to the Subversion exclude list before the initial check in, so the process is a bit more involved than I wish.  The easiest way to get a project checked in  correctly is to just to delete the files that should not be checked in before sharing the project.  Then, after the project is synchronized with the repository, perform a Worklight build to regenerate these files and folders.  At this point, they can be added to the Subversion exclude list.

The files to exclude from check-in are:

Everything in bin  In general this means that *.adapter, *.jar, *.war and *.wlapp needs to be added to svn:ignore on bin.  There is a hidden classes folder in bin that ought to be automatically marked as derived, but I've seen at least one case where it didn't have the derived flag set.  (this might have been a project migration issue)  In any case, for good measure I add classes to svn:ignore on bin and watch the initial check in carefully to make sure that bin/classes isn't getting checked in.  

In an android environment:

• native/assets/www
• native/assets/wlclient.properties

In an iOS environment:

• native/CordovaLib
• native/Frameworks
• native/WorklightSDK
• native/www
• native/worklight.plist
• native/<name>.xcodeproj/project.xcworkspace/xcuserdata
• native/<name>.xcodeproj/xcuserdata
• package

The xcuserdata folders won't exist unless you have opened the environment in XCode at least once.  When you delete them in your workspace, you will lose the XCode workspace configuration (selected run target, open windows) but won't lose project content.  In general, xcuserdata folders should be excluded from SCM wherever they exist.  I've seen cases where XCode puts xcuserdata folders in other parts of the project tree, but the above locations seem to be consistently created.

One way to deal with xcuserdata is to add it to Preferences -> Team -> Ignored Resources.  This will result in xcuserdata folders being ignored anywhere in the project tree.  However that preference needs to be set on every workspace that checks out the project, so as tedious as ignoring that folder individually wherever it pops up, that is probably the safest solution.

Unfortunately, in my testing on OSX, in the iOS environment, even though native/CordovaLib, native/Frameworks and native/WorklightSDK get regenerated on the first build after checkout, they (or in the case of native/Frameworks, a subdirectory) get regenerated with the wrong permissions.  You may not even notice this until it is time to delete the project from the workspace, and you find that the delete operation fails.  Another symptom is that when you open the environment in xcode, it reports that the CordovalLib project is locked, and offeres to unlock it for you.

The solution is to right click on native/CordovaLib, native/Frameworks/sqlcipher.framework, and native/WorklightSDK.  For each folder, select Properties, in the Permissions area, check Owner: Write, and click on Apply.  You will be prompted as to whether you want to apply the changes to subfolders.  Click on Yes.   This only needs to be done once after checking out the project.  Subsequent builds do no alter the folder permissions.

Mobile Web environments can be checked in as-is. I don't have notes for the other environments.   The Infocenter is the best resource for now.  If I have occasion to look look into the details of other environments I'll circle back and update this post.

Once you have removed the files that should not be added to source control, right click on the project and select Team -> Share Project.  Select SVN and click on Next.  At this point, if you have already defined the repository location in the SVN Repository view, you can simply select it.  Otherwise, you can configure it here.  The repository must exist and be initialized.  See the Subversion documentation for notes on how to set up a repository and how to address the repository.  When I am using a local repository, I tend to just use a file:/// URL.  When I am using a remote repository, I tend to just use svn+ssh:// but any access method should work.

I've been trying to follow the Subversion naming conventions.  This is one area where Subversive is ahead of Subclipse.  In Subversive, the standard naming convention is supported by default.  In Subclipse, you need to manually manage the name at check in.

Once the folder is specified, click on Finish and the project will be associated with your repository.  (but nothing will be checked in yet)  The Synchronize view should open automatically.  You can review what is getting checked in to be sure that you didn't miss anything.  When you are happy with the list, right click on the project in the Synchronize view and select Commit...  This will give you the chance to add a comment, and click on OK to commit to the repository.

If you are checking in a dojo app, this is a good time to get a cup of coffee.  Because there are so many files under the dojo folder, initial check in and check out of dojo apps is quite slow.  But since the files in the dojo folder should (almost) never change, subsequent synchronization is just fine.

Once the project is checked in, build the app and add the ignores.  Subversion manages the ignore list through the svn:ignore property on the containing folder.  Once a project is checked in to the repository, a new file in the project can be added to the ignore list by right clicking on it and selecting Team -> Add to svn:ignore.  This opens a dialog that gives you the option to ignore the file explicitly by name, by file extension, or using a custom wildcard.  This method is handy for ignoring 1 or 2 files or patterns in a directory.

If you are adding several ignore patterns to a folder, You can right click on the folder, and select Team -> Show Properties.  This will open the SVN properties view.  Here you can right click and select: Add a property.  The property name is svn:ignore and the value is a newline delimited list of patterns to ignore.

Once you have set up all the svn:ignore properties, synchronize again. (right-click on project: Team -> Synchronize with Repository)  Only the folders containing ignored resources should have changes.  The files that you are ignoring should not show up in the Synchronize view.  I have seen a problem with Subclipse where files were showing up in the Synchronize view as being added even though I had set the ignore pattern for them.  I had to restart Eclipse to get Subclipse to work it out.

If you do accidentally get a file that shouldn't be in the repository checked in, adding it to the ignore list won't help.  You need to delete the file, synchronize with the repository and then add it to the ignore list.

And that's it.  I've used Git with Worklight Studio with very mediocre results.  That is probably more to do with my lack of understanding of Git than with actual problems.   I've also used Rational Team Concert.  That is much more than an SCM system, but it does include SCM and it worked well with Worklight Studio.  I should probably circle back and look at it with Studio 5.0.5 and Eclipse Juno.