TeamForge- Enabling Collaboration

CollabNet TeamForge provides not only the tools that are necessary to manage and track all stages of your software development lifecycle, but also the integration between these tools that you need in order to link such things as work items, commits, reviews and builds.  It is this tight integration between all the important application lifecycle stages that enables your teams to collaborate most effectively.

In this blog I am going to focus on the linkage between your Git or Subversion code commits and your work items, such as requirements, user stories, tasks, issues and bugs.

Associations

To provide some context, let’s look at how TeamForge implements an association between two items or events, such as a work item and an SCM code commit.

Almost every type of TeamForge entity or event, including change requests, documents, discussion topics, wiki pages, commits and builds, to name a few, has an object ID associated with it.  The object ID consists of a prefix that identifies the type of object, followed by a number that makes the ID unique.  For example:  artf50021 (artifact), doc1423 (document), topc1005 (discussion topic), wiki2509 (wiki page), cmmt9248 (commit), etc.

Based on these object IDs, associations can be created between any two TeamForge objects.  In this screenshot I am manually adding an association to a tracker artifact by selecting a recently edited document:

Image may be NSFW.
Clik here to view.

Associations can be created manually using the TeamForge web UI or one of the TeamForge desktop clients, but they can also be created automatically at many key points in the application lifecycle, such as when code changes are committed to your TeamForge source repositories, which is what I will demonstrate in this blog.

Automated Commit Associations

When a commit is made to a Git or Subversion repository, an automatic association will be created whenever the commit message contains “[objectId]”, where objectId is a TeamForge object ID, as described above.

Here is an example Git commit that, when pushed to the TeamForge repository, will result in an association between a commit and an artifact:

Image may be NSFW.
Clik here to view.

Keep in mind that a Git commit is entirely local, so the TeamForge association will not be created until the commit is pushed to the server.

Here is a similar example of a Subversion commit that will result in an association between a commit and an artifact:

Image may be NSFW.
Clik here to view.

Here you can see that the above commit has created the association, which is visible in the Associations tab of the artifact:

Image may be NSFW.
Clik here to view.

Notice that there are also several other associations that have been added previously, including a link to a post in a discussion forum in which a user asked for the feature, and also a link to a document in which the user’s requirements were captured.

Now that we have the association, it can be useful for navigating in either direction.  For example, suppose someone wants to know what files I changed as part of the work that I did for this artifact.  They would click on the commit link in the Association column (above screenshot) to go directly to the commit details:

Image may be NSFW.
Clik here to view.

On the other hand, suppose I am coming at it from the opposite direction; I am browsing the repository and want to know the details behind why a particular change was made.

Image may be NSFW.
Clik here to view.

In this case I can simply click on an artifact link for a particular revision.  This will open the artifact so that I can read the description and comments, and perhaps trace other associations found in the artifact.

Require Associations for Commits

Based on compliance requirements or the best practices of the organization, a project administrator might configure the Git or Subversion repository such that a commit will not be allowed without an association.  This is as simple as selecting a checkbox in the TeamForge repository definition:

Image may be NSFW.
Clik here to view.

Git and Subversion Clients

I’ve showed you how to associate your commits and artifacts by including “[<objectID>]” in the Git or Subversion commit message, but this can be tedious and error prone.  If you are committing from the command line, an omitted bracket or an incorrect artifact ID can easily cause your commit to be rejected.

Fortunately, most Git and Subversion clients include UI features that make it easy to choose the correct artifact and ensure that the format of your commit message is correct.  Some examples are shown below.

CollabNet Desktops

The CollabNet desktops include several features to help you with your commit messages.

Create Log Message in Clipboard

The context menu for an artifact anywhere in the Eclipse edition or the Visual Studio edition of the CollabNet desktop includes an option that will format your commit message based on the selected artifact and put it in your clipboard:

Image may be NSFW.
Clik here to view.

You can then paste from the clipboard when composing your commit message:

Image may be NSFW.
Clik here to view.

Mylyn Task Management (Eclipse Edition only)

Since the Eclipse desktop includes Mylyn, another option is to use Mylyn’s task-focused interface to automatically populate your commit messages.

In the Mylyn preferences, you define a template for your commit messages:

Image may be NSFW.
Clik here to view.

Note:  I have modified the default template by adding the brackets around the ${task.key} variable and removing the Task-Url from the template entirely.  The original template looked like this:

${task.key}: ${task.description}

Task-Url: ${task.url}

With your commit template in place, you activate the artifact that you are working on:

Image may be NSFW.
Clik here to view.

As you work on your changes, Mylyn will maintain a link between the files that you change and the active artifact.  This allows you to switch between tasks without committing and then, when you are ready to commit, include just the changes that are associated with the active artifact.

When you are ready to commit, your commit message will be pre-filled based on the commit template and the active artifact:

Image may be NSFW.
Clik here to view.

Note that, although this screenshot shows a Subversion commit, the same workflow applies for Git commits as well.

CollabNet Desktop – Visual Studio Edition

Since the Visual Studio edition is not Eclipse-based it of course does not include Mylyn.  It does, however, implement its own equally effective features for obtaining similar functionality.  Although I’m not demonstrating that in this blog, you can read about the specifics here.

GitEye

GitEye is a GUI client for Git written on top of the Eclipse RCP framework, with complete support for CloudForge and TeamForge.  It is not an IDE and does not repackage the Eclipse IDE but, because it does include the CollabNet Desktop for Eclipse (with the exception of Subversion support) as well as Mylyn, the techniques shown above can also be used in GitEye.

Another option, unique to GitEye, is that you can select artifacts from the results of custom tracker queries and drag them to the commit message.  When the artifact is dropped, the commit message will be formatted appropriately so as to create the association between the commit and the artifact.

Image may be NSFW.
Clik here to view.

Subversion Bug Tracking Properties

Most Subversion clients, such as Subclipse, TortoiseSVN and AnkhSVN, will look for certain Subversion properties which start with “bugtraq:”.  If these properties are found the client will, based on the property values, provide a place in the UI for issue ID’s to be entered and perform some simple validation.  Also based on property values, it will insert the properly formatted issue ID in the commit message.  When reviewing Subversion history, these bugtraq properties can even serve to convert references to issues in the commit messages to hyperlinks to the issue tracker.

Here is an example of bugtraq properties for a project in a TeamForge Subversion repository:

Image may be NSFW.
Clik here to view.

And here is an example of what the commit dialog might look like based on the above bugtraq properties:

Image may be NSFW.
Clik here to view.

Finally, here is an example of Subversion history showing how the commit message for the above commit has been automatically formatted so as to create an association to the artifact:

Image may be NSFW.
Clik here to view.

In the TortoiseSVN repository you can find the full specification (username = “guest”, no password) for the Subversion bugtraq properties.

Conclusion

I’ve shown you how TeamForge commits can be automatically linked to tracker artifacts.  If you are not already a TeamForge user and would like to see this for yourself, you can sign up for a free CloudForge account and within minutes you can be hosting your TeamForge project along with your Git or Subversion repository on your own private cloud.  If you want to take it a step further, you might be interested to read about how TeamForge Orchestrate can provide even more automated traceability and valuable views into the relationships between all your favorite ALM tools.

The post Linking TeamForge Commits and Artifacts appeared first on blogs.collab.net.