Notes/Domino 8.5.3: Using version control

October 21, 2011

One of the big new features in IBM Lotus Notes 8.5.3—specifically, in the Domino Designer—is support for external version control tools. To me, this is the single best thing ever to happen to Notes and Domino. Here’s how to use it.

Start off by opening your database in Domino Designer. Right-click the icon, choose Team Development from the popup, then choose Set Up Source Control for this Application.

Go through the wizard which appears. Give your project a name, and set the location on disk where files should be placed. (If you override the default, the location you choose should be a directory where you want the files to go, so you’ll probably want to create one.)

Now the magic happens. Notes writes out the entire design of the database, as a set of files neatly arranged in the following subdirectories under the project directory:

WebContent
Forms
Pages
Resources
Resources/Files
Resources/StyleSheets
Resources/Images
SharedElements
SharedElements/Columns
SharedElements/Subforms
SharedElements/Fields
SharedElements/Outlines
Views
Code
Code/ScriptLibraries
Code/Actions
Code/Agents
Code/WebServices
AppProperties
Framesets

Now you can open up the project directory that contains those folders, and stick the whole thing in version control. For example:

$ cd ~/workspace/MyProject
$ git init
$ git add *
$ git commit -m 'Initial import'

Congratulations, your Domino database is now under version control. You can tag releases, examine changes, fork and merge, and do all the other great stuff version control allows. I run RedMine at work, and push each bug fix as a commit to a repository on the machine. I put the number of the ticket in the commit message, and RedMine automatically cross references everything and makes the changes browsable.

Browsable? Yup, because most of the files Domino generates are XML, in Domino XML (DXL) format. There are still a few binary blobs, but I hear that these will gradually become DXL too. So changes to views, form fields, agents and the like can sensibly be examined in version control. And of course, all your LotusScript, ECMAScript, CSS and HTML resources are there in plain text.

This also means you can grep all your source code. Or even better, use ack, which by default will skip the GIFs, JPEGs and other binaries.

Behind the scenes, the Domino Designer watches the directories and the NSF file, and synchronizes changes—bidirectionally. Change something in the Design client, and it gets quietly updated on disk. You can edit a style sheet file in $PROJECT/Resources/StyleSheets using Vim; when you save it, Notes notices and updates the NSF. There’s a manual sync option for when you want to be absolutely certain everything’s in sync (say, before a commit), but for general development everything seems to work automagically.

This is the best thing to happen in the world of Notes development since… since ever. All I want now is a non-Windows Domino Designer and I’ll be happy.

Filed under: Domino | Comments (0)