Use SourceTree for better XPages Source ControlA transcript +

Patrick Kwinten

14

ContentsIntroduction.................................................................................................................................................3

Document History........................................................................................................................................3

Terminology.................................................................................................................................................3

Links of interest............................................................................................................................................3

Pre-preparation............................................................................................................................................4

Remove source control plugin from Domino Designer.............................................................................4

Preparation..................................................................................................................................................4

Install SourceTree.....................................................................................................................................4

Set local storage.....................................................................................................................................10

Mercurial in examples........................................................................................................................10

General thoughts using source control..................................................................................................10

Working with SourceTree...........................................................................................................................11

Turn a local folder into a repository.......................................................................................................11

Associate a NTF/NSF with an ODP in Domino Designer..........................................................................13

Ensure sync between NTF/NSF and ODP in Designer.........................................................................19

Smart branching with Hg Flow...............................................................................................................22

In the beginning…...............................................................................................................................23

Initial Commit.....................................................................................................................................24

Hg Flow action....................................................................................................................................25

Create a Feature.................................................................................................................................27

Create another Feature......................................................................................................................33

Create a Release.................................................................................................................................37

Working with Hotfixes........................................................................................................................40

Submitting to Bitbucket..........................................................................................................................50

Create a repository.............................................................................................................................50

Setup remote repository in SourceTree.............................................................................................52

Push ODP to Bitbucket.......................................................................................................................54

Pulling from Bitbucket............................................................................................................................55

Clear your files....................................................................................................................................56

Recreate NTF/NSF from code on Bitbucket........................................................................................59

Summary....................................................................................................................................................67

IntroductionThis document handles how to use SourceTree within XPages/Notes development. Rather than using source control inside Domino Designer, SourceTree is an external application for committing your Domino project code.

SourceTree is free and supports Git and Mercurial (distributed version control systems).

This document describes how to use SourceTree with your XPages applications and contains examples how to push project code to remote repository or pull code back from that remote repository into an application.

This document only focuses on XPages development and only describes the basics of SourceTree. You are invited to complete the document by sending your additions to the author.

Document HistoryVersion Date Author Description0.1 2014-01-09 Patrick Kwinten Initial draft1.0 2014-01-15 Patrick Kwinten Initial release

TerminologyTerm DescriptionSource Control Source Code Control System (SCCS) is an early revision control

system, geared toward program source code and other text files.ODP On disc project. Representation of NTF/NSF file that can be used by

version control systems.DVCS Distributed Version Control System.Hg A synonym for Mercurial.

Links of interestSite Description LinkSourceTree A free Mercurial and Git Client for Windows and

Mac that provides a graphical interface for your Hg and Git repositories.

Link

Bitbucket Bitbucket is a free code DVCS hosting site for Git and Mercurial.

Link

Notes in 9 Episode 131 David Leedy demonstrates SourceTree in this video-tutorial. His tutorial has functioned as a sort of transcript for this document.

Link

Smart branching with SourceTree and Git-flow

Explanation about the branch management capabilities in SourceTree.

Link

Pre-preparation

Remove source control plugin from Domino DesignerIn case you have worked with source control before from within Domino Designer I guess it is best to remove those plugins because you probably won’t need them anymore. SourceTree works completely outside Domino Designer so it is advised to get rid of current source control plugins in case they should exist.

Preparation

Install SourceTree Probably the first step will be to download and install the SourceTree software. It is available

from the SourceTree site. Run the setup.

Select a directory to install the software.

Finally you will be asked if you would like to run the program.

Select Finish and leave the launch option checked.

At first the program will start with the setup. It is not sure where the user information is collected from.

Select Next.

Select Use PuTTY.

Select No. An SSH key at first is not required.

In the examples in this document we will store our project code on Bitbucket. Bitbucket is a free DVCS hosting site for Git and Mercurial. In case you have not already a Bitbucket account we suggest you to create one here.

Enter your Bitbucket credentials in the SourceTree setup dialog. Press Finish.

‘Corporate’ developers are asked probably to authenticate with the proxy.

Voila! You have just installed SourceTree.

Set local storageYour project code is going to reside initially on a local repository on your machine. From there you will submit the code to the online distributed repository on Bitbucket.

Create a folder on your machine e.g. in the (My) Documents folder. Name it Source Control or something.

Open the Source Control folder and create two more folders, call one Git and the other Hg.

Mercurial in examplesIn the examples we use Mercurial as repository. Russel Maher has released a couple of video tutorials on using Mercurial as DVCS (link). However he demonstrates the usage of a plugin in Domino Designer.

General thoughts using source control Submitting and receiving code from a DVCS is done with a local replica.

o From this local replica you can distribute the changes to an application on your QA server (or Development server).

o It is discouraged to use a shared replica (on a Development server) instead of a local replica.

The local replica is associated with an On Disc Project (ODP) on your local machine (or location on your network).

Domino Designer will take care of the synchronization between the ODP and the NTF/NSF. SourceTree will submit the ODP to a DVCS e.g. Bitbucket.

Each application is going to have its own subfolder to store the project code. An application may consist of multiple NTF’s. Each NTF will reside in the same subfolder.

Open the Mercurial (Hg) folder. Create a folder e.g. Demo1.

Working with SourceTree

Turn a local folder into a repository

Select the Clone/New action in the SourceTree program.

Select the Create New Repository tab.

Select Mercurial as the Repository Type. Select the Demo1 folder you have created under the Documents\Source Control\Hg as the

Destination Path. Select Create.

So what did these actions just do? In the Demo1 folder a folder is created to store the change log, commits, reversions etcetera.

Remember that anything (e.g. a Notepad file) you put under the Demo 1 folder is going to be under Source Control.

Beside the .Hg folder in the Demo1 folder create a second folder and name it e.g. Demo1 ODP (On Disk Project).

Associate a NTF/NSF with an ODP in Domino Designer

Create a new NTF/NSF in Domino Designer.

Select Team Development\Set Up Source Control for this Application.

Select Next.

Enter a name for the project e.g. Demo1. (!) Uncheck the default location. Browse for the folder you previously created under Documents\Source Control\Hg\Demo1.

Select OK. Select Finish.

Notice both the NTF/NSF as the ODP in Designer.

Notice the ODP files on your local machine.

Ensure sync between NTF/NSF and ODP in DesignerDomino Designer is responsible for synching the code in the NTF/NSF and the ODP. In order to keep changes in sync you must tell Domino Designer to update changes instantly.

Open the Preferences in Domino Designer.

Open General\Workspace. Check the Refresh automatically option. Select Apply.

You can check this enablement as followed:

Open the Forms folder in the ODP. Notice it is empty. Open Domino Designer and create a Form design element e.g. ‘dummy’.

Select OK. Open the Forms folder in the ODP folder again. Notice the dummy.form file.

In case you open this file you see the Form design element presented in XML format:

Smart branching with Hg FlowBranching is the duplication of an object under revision control so that modifications can happen in parallel along both branches.

Hg Flow in SourceTree allows you to work with the following branch structure in your repository:

Development branch (usually called ‘develop’). Production branch (usually called ‘master’). Feature branches (usually prefixed with ‘feature/’). Release branches (usually prefixed with ‘release/’). Hotfix branches (usually prefixed with ‘hotfix/’).

The next image gives an overview of how these branches flow normally:

In the beginning…When you open SourceTree you won’t find any branches for your project:

Under tab Log/History you notice there are uncommitted changes:

Initial CommitYou are ready to make your initial commit in SourceTree.

Select the Commit action under Repository.

Enter a Commit Message.

Note it is expected you add a message to every commit so others can understand the applied change(s), especially with the first commit.

Select Commit.

Confirm the addition. Select OK.

Notice there is now 1 Commit to be pushed to the distributed repository but we will touch this later:

Hg Flow actionNotice some other actions for Repository:

1. Branch2. Merge3. Tag4. Hg Flow

The first 3 are combined under Hg Flow. Hg Flow can be seen as sort of a wizard that performs branch management for you (link).

Click on the Hg Flow action.

Hg Flow setupIn a dialog SourceTree asks you where to create the branches for:

Production (your ‘Gold code’, final code before release)

Development (your QA code, code for testing) Feature Release Hotfix

Accept the default locations and select OK.

Select Yes.

As a result you see above.

Create a Feature

Select the Hg Flow action. Select Start New Feature.

Enter a name for the feature. Select OK.

Create a Dummy Element in Domino Designer.

Now watch in SourceTree as there are now Uncommited changes to commit.

Commit the feature

Select the Commit Repository action.

Notice in the dialog what files have been touched.

Include a message for this Commit action and select Commit.

Select OK to confirm.

Notice the result.

Finish the feature

Once again select the Hg Flow action.

Choose to Finish this Feature.

Select OK.

Note: It is considered best practice to keep your features small e.g. ‘Feedback form’ instead of a collection of updates.

Develop branch createdNotice also the branching going on:

Notice also how the branch moved back into the develop trunk:

In Domino Designer:

Switching branches & Domino DesignerIf you switch in SourceTree back to the default branch notice the feature is removed from the NTF/NSF:

In SourceTree double-click the default branch.

Notice how the feature (Dummy XPage) is not available in Domino Designer:

In SourceTree switch back to the develop branch.

Create another Feature

Select again the Hg Flow action.

Select to add a New Feature.

Notice that SourceTree has recognized the existing of the develop branch.

Create in Domino Designer a new design element e.g. a SSJS library.

Notice the Uncommitted changes:

Commit the feature

Once again Commit the changes.

The key is to commit your changes BEFORE you close your branches.

Enter a message for this commit. Select Commit.

Select OK to confirm your Commit action.

Finish the feature

Notice that the feature still resides on its own and is not part of the develop branch yet.

Select the Hg Flow action.

Select the Finish Feature option.

Select OK.

Notice you have now performed two feature additions.

Create a Release Select the default branch.

Select the Hg Flow action.

Choose the New Release option.

Enter a name for the release. Select OK.

Notice the release .01 branch created:

Finish the release

Select the Hg Flow action again.

Select the Finish Release option.

Notice in the graph that the action will put everything into the develop branch and also into the default branch:

Notice how the features & release have landed in the production (default) branch:

Working with HotfixesIn this scenario you are asked during the development of a new feature to quickly implement a hotfix. This means you must drop your current development, apply the hotfix and release it asap. After this you can continue to work on the feature you were working on.

Create a new feature

Select the Hg Flow action. Select Start New Feature.

Enter a name for the feature. Select OK.

Create the design element in Domino Designer.

Incoming Hotfix requestIn this stage you receive a request to fix a critical problem in the production code a.s.a.p. It is important to commit your current work first.

Select the Commit action under Repository.

Include a message for this Commit action and select Commit.

Select OK to confirm.

Notice the result:

Create a Hotfix

Select the Hg Flow action again.

Instead of finishing this feature select Start New Hotfix.

Enter a name for the Hotfix. Select OK.

Notice how SourceTree manages to identify to do this from the default branch.

Notice in the graph that feature 3 is at the moment not in the default branch.

Create a new design element under the Hotfix 1 branch.

Also update one of the previously created design elements.

Notice the Uncommitted changes:

Commit the Hotfix

Select the Commit Repository action.

Enter a message for this commit. Select Commit.

Select OK to confirm your Commit action.

Finish the Hotfix

Select the Hg Flow action again.

Select Finish Hotfix.

Notice in the graph that this hotfix is going into develop and default at the same time:

Select OK.

Switching branchesIn case you switch now between branches develop and default in SourceTree you notice in Domino Designer the hotfix changes applied. However feature 3 is not available here.

Switch to develop branch.

Notice the custom control created under feature 3 is missing:

Continue with your feature

Now switch to the feature 3 branch.

Notice the (unfinished) custom control becomes available now in Domino Designer:

When you finish this feature use the common path e.g. commit & finish feature to move it into develop.

Submitting to BitbucketIn case you are working within a team or you want to store your project code with history you will need to send it to a DVCS.

Create a repository Visit the Bitbucket site (link).

Create a new repository.

Enter the details for the repository. Select Mercurial for the Repository type. Notice you can select XPages as Language =)

Select Create repository.

You will be directed to the overview page for the created repository.

Select the I’m starting from scratch link.

Setup remote repository in SourceTree

Select and copy the URL that will be presented to you under Clone.

Select the Settings action in SourceTree.

Select the Add button.

Enter the details for the Remote repository. In URL/Path enter the clone URL received from Bitbucket. Select OK.

Select OK.

Notice the Remote repository appearing for this project:

Note that SourceTree you can use HTTPS or SSH (secure shell) to connect to Bitbucket. HTTPS is more suitable in case you work infrequently with Bitbucket and make few changes. More information can be found here: link.

Push ODP to BitbucketNotice SourceTree has identified that there are changes to Push:

Select Push.

Select OK.

Notice in Bitbucket under the Source tab the project code is now available:

You can read the full code of your design elements:

Pulling from BitbucketDue to different circumstances the initial code resides only in Bitbucket and not on your local machine (e.g. new installation, invitation to join a project, an open sourced project, etcetera).

Clear your filesSince we demonstrated first how to associate an NTF/NSF with an on disc project and how to use SourceTree with the ODP we have already code on our local machine. You should perform the following actions first.

Delete NTF/NSF in Domino Designer Delete the NTF/NSF.

Select in Domino Designer File\Application\Delete. Select Yes.

Delete on disc project in Domino Designer

Open the Package Explorer Eclipse view in Domino Designer.

Select the ODP for the application.

Select Delete.

Select OK.

Delete repository in SourceTree

Highlight the repository, right-click and select Delete.

Select the Delete Repositories on Disk option.

Select Yes to confirm the removal.

You can check the result of this action. The local storage folder is made empty:

Recreate NTF/NSF from code on BitbucketSo how do you get the code from Bitbucket back into an NSF?

Clone a repository in SourceTree Open the repository on the Bitbucket site.

Copy the URL to clone a repository.

Select the Clone/New action in SourceTree.

Copy the URL in the Source Path /URL. Select the local storage folder as Destination Path. Select Clone.

Notice the result of your cloning:

And notice the repository files on your local storage folder:

Import repository to an ODP project in Domino Designer Open in Domino Designer the Package Explorer Eclipse view.

Select Import.

Select General\Existing Projects into Workspace. Select Next.

For Select root directory browse for the ODP project of your local repository. Select OK.

Make sure the Copy projects into workspace option is unchecked. Select Finish.

Notice the ODP files are now back in Domino Designer:

Create NTF/NSF from the ODP in Domino Designer

Right-click the ODP and select Team Development\Associate with New NSF.

Enter a name for the file. Select Finish.

As a result you can open the application an navigate through the design elements:

Notice that feature 3 (the custom control) is not in this NSF since you never finished that branch so it never made it into the production code.

Note: When I tried to switch in SourceTree back to this feature branch I get an error message:

SummaryIn case you work in a team on the development of an application I suggest you and your team should take a look at the source control capabilities in SourceTree.

It allows multiple developers to work concurrently on the same application design without the threat of potential conflicts.

SourceTree produces a comprehensive audit trail of the development process, allowing developers to track their design changes.

As this document or manual demonstrates the setup of SourceTree and integration with Domino Designer are pretty easy.

Here follow some recommended resources that can help you understand SourceTree:

Atlassian Q&A tagged on SourceTree: Link. Youtube with a search after sourcetree and tutorial: Link.

Good luck & enjoy development!

Patrick Kwinten