Imagine the scene… You’ve started using source control for your applications in IBM Domino. You’re comfortable with the way it’s going and enjoying all the rewards that this brings; good code backup, great history and reviewing facilities, ability to try “what if…” scenarios with branching, and easily reverting to the original if it doesn’t work out. That’s aside from the more obvious advantages of organising development/test/live applications and their releases.

The advantages above apply even if there’s no collaboration with other developers, but if you need to bring other developers into the mix, how do you get them ‘on board’ with source control, given that the repository already exists? The steps below show reveal how to do this.

1) Have the new developer clone the repository to their local disk.

  • From Bitbucket website (if using Bitbucket):
  • Navigate to repository
  • Click ‘clone’ in SourceTree
  • Fill out further info, eg destination (local) file location

OR

From SourceTree:

  • Click ‘clone’
  • You need to know the repository URL, or you can browse repositories shared with you by clicking the ‘globe’ icon on the ‘clone repository’ popup.
  • Set (or select) the URL, destination file path for the repository, and repository name

Cloning a local repository can take a while as there could be a lot of data to download. SourceTree shows a horizontal ‘flow bar’ but not really a progress bar, so you have to let it have its moment. I’ve known this to take a few minutes.

You should now have, somewhere on your file system, a local repository. It’s likely it’ll be a directory named after the source repository. Within this – perhaps within further sub-directories (depending on how the repository is set up) – there should be a “nsf” directory (this is our Oval standard).

Once you’ve got the local repository, you need to check out the correct local branch. In SourceTree, expand the ‘Remotes’ list, and double click the appropriate branch to ‘check it out’ (take a local copy).
With Oval applications, this branch is usually “develop” but it may vary, so check with the project lead.

2) Register the repository as an On-Disk-Project in domino designer

An On-Disk Project (ODP) is like a design-only replica of your nsf file, but represented entirely with text/xml files.

From Domino Designer:

  • Open the ‘Package Explorer’ view.
  • Single right-click in the white space of the view somewhere. Choose ‘New .. Project’.
  • Select ‘General / Project’
  • Enter the project name. It’s best to start it with “ODP <whatever you like>” because the nsf file representation gets included in the list too, and it could be easy to confuse the two. The <whatever you like> probably ought to be the same as the repository name.
  • De-select the default location and navigate to the nsf directory of your new GIT repository.
    At this point, it might feel like you’re about to overwrite the repository. In fact all you’re doing is registering a pointer to that file location.
  • Click ‘next’ – and ignore this step. This shows a list of ‘related projects’ which may become relevant, but probably isn’t now, so click ‘finish’.

3) Create a new NSF file from the ODP

  • From Package Explorer, locate your new ODP (expand it to check it has some elements as expected)
  • Single right-click and choose ‘team development/associate with new NSF’. You’ll be asked for a server and file location only. This is going to create a new NSF file from your ODP, which includes the ACL, db title etc already.
  • Select the server and enter the directory and nsf file name (include .nsf).
    Once you click ‘OK’, you’ll see the progress of the application being imported. This works a bit like a “New Application” dialogue box, in that an icon is added to your current workspace.

4) That’s it!

You now have an application, ODP, local repository and connection to Bitbucket via SourceTree.

When you edit the design, do this as usual from the applications list in Designer (not the ODP). This means your changes will be apparent in the application immediately. If you change the ODP manually, there will be synchronising to do before it appears in the application design.

Further notes

When you’ve made a change and want to commit to GIT via SourceTree:

  • Single right-click on the application in Designer and choose ‘Team Development/Sync with On Disk Project’. This ensures your ODP is up-to-date with your nsf file changes.
  • Go to SourceTree and, in the Uncommitted Changes list, you’ll see the changes you’ve made. You may also see a load of extra files ending in .metadata. These just hold the signature and last-accessed info, so aren’t important to the design, but there’s no harm in committing those too. You can also add them to the Sourcetree ‘ignore’ list by single right-clicking one of these files in SourceTree, and clicking ‘ignore’. A popup will ask you the criteria of what you’d like to ignore. Select the option for any file of type “metadata”

When a change has been made elsewhere and you want to pull it from the repository and merge it to your design:

  • Pull the changes into your branch in SourceTree; this applies them to the disk representation.
  • From Package Explorer in Domino Designer, single right-click on your ODP.
  • Choose ‘Refresh’. This doesn’t always appear to do anything but is more a safety measure.
  • Single right-click again on ODP and choose ‘sync with nsf’. If there are a lot of changes, you’ll see the progress icon at the bottom left blip for a bit.
  • You might see conflicts if you have changes in the nsf file and in the ODP (a bit like rep/save conflicts). If so, a popup will ask you which should ‘win’. Assuming you commit your design to GIT fairly often and people pull the changes, this should be very rare, so think about which one should win and choose accordingly.

Some advocate disabling automatic import/export from NSF to ODP (see Domino Designer Preferences, under Domino Designer > Source Control, with two checkboxes for import and export).

If you’re developing on a local server, and your ODP is held locally, then having this set on means the sync usually happens automatically as you develop, so when you come to commit changes there’s little/no sync to do.

However, if you’re developing on a server, then each change you make to the nsf file will try to sync with your ODP right away. This may or may not hinder Designer – your call.

Either way, when you commit changes, make sure the ODP and nsf are synched first, and when you pull changes, sync the nsf and ODP afterwards.

Domino is a bit biased in this repect; when making changes on your nsf, and if you have automatic export set, designer syncs the nsf for you immediately. You’ll see the changed files registered in SourceTree as Uncommitted Changes immediately.

When you pull changes from GIT, it fails miserably and you have to refresh the ODP and sync the nsf file with ODP manually.