Walk-through: Connecting Eclipse to TeamForge Project
Today I thought I would walk through the necessary steps to configure the CollabNet Desktop Client for Eclipse and connect it to a TeamForge Project running on Codesion. This blog post should apply to Eclipse and other tools written on the Eclipse platform. I'm using the "Indigo" 64-bit build of Eclipse on OS-X but I have followed the same steps with similar success with VMWare's SpringSource on OS-X and Eclipse on Windows 7. I'll assume you have a working copy of Eclipse for this walk-through and a passable knowledge of how to use it.
To complement its incredible extensibility, Eclipse also provides its own built-in package management. This allows users to add tools on-the-fly without having to leave Eclipse. In the latest incarnation they have added a "Marketplace" to make searching for new tools and plug-ins that much easier. Once you have Eclipse installed and running, click on "Help->Eclipse Marketplace":
Once you have that open, simply search for "CollabNet" and install the "CollabNet Desktop - Eclipse Edition". This will install everything you need to not only manage your TeamForge project but also connect to your subversion repository and integrate TeamForge tasks with Mylyn, Eclipse's built-in task manager. Depending on your network connection and computer speed, it might take a few minutes to download and install all of these packages. You will also be prompted to restart Eclipse to integrate the new packages.
Don't fret if your version of Eclipse doesn't include the marketplace. If you follow these directions you can install the "CollabNet Desktop" via Eclipse's original package manager.
Okay, Eclipse should be up and running again and it probably looks exactly the same as it did before we installed the CollabNet Desktop. Your workspace might look quite a bit different than my screenshots. That's because I'm using the default Java Perspective and only have the "Package Explorer" and "Task List" views open to keep things simple. Feel free to customize your own perspective to your heart's desire.
Now let's add a view for the CollabNet Desktop. Click on "Window->Show View". CollabNet probably won't be listed on this pop-out menu but you can click on "Other" at the bottom of the menu.
Scroll to the "CollabNet" folder and choose "CollabNet Sites". This will add a view named "CollabNet" somewhere in your current perspective. The CollabNet Desktop also provides its own perspective to Eclipse and it can be shown by clicking on "Window-Open Perspective." The CollabNet perspective is focused on task management and repository synchronization but I prefer to structure my work from the perspective of the code, adding task views and repository views to my code perspective. Eclipse is flexible enough to allow for any working perspective so just choose what works best.
Activate the CollabNet tab in the current perspective. Three sites should be included by default:
CollabNet TeamForge Community
We're going to ignore these but feel free to explore them for access to CollabNet's extensive communities for both TeamForge and Subversion. Right-click somewhere in this pane and choose "New-CollabNet Site"
In this dialog we are going to choose to add a new "CollabNet TeamForge" site.
To connect this site to your Codesion TeamForge project enter the url: https://teamforge01.codesion.com/ (Make sure you include the "s" for an SSL connection here. Otherwise the server will try to redirect you to the SSL port and the connection will fail to properly connect to the API.) Give it a description that will be meaningful to you. Your username and password will be the same as your Codesion credentials:
Once you have configured this new site it should appear in your CollabNet view. This site will also be added to your project as a Task repository:
You can add queries to this Task repository and load all artifacts directly from TeamForge into your project.
If you would rather see your tasks in a shared Agile task board or a project planner you can also right-click in the CollabNet view on the project you want to open and select "Open With..."
This is an example of an Agile task board within Eclipse. All of the Product Backlog Items and Tasks are stored within TeamForge so any changes made by dragging and dropping will be reflected in the project and immediately available for the rest of the team. If you want more details on how to set up the task board I highly recommend reading this blog post which describes it in more detail.
Now that our project reflects all of the tasks we need to accomplish for this product let's add some source code and tie everything together. To begin, I'm going to load my existing code from my Codesion SVN repository. All of steps prior to this will work just as well for Git. The following steps are specific to Subversion. I'm going to choose "File->New Project" and add code from my repository.
If you haven't done so already you will be asked to add a new repository. Use the URL for your project in Codesion:
https://<domain>.svn.cloudforge.com/<project>
On this screen make sure you change how it will be checked-out to "Check out as a project in the workspace." I didn't change this at first and Eclipse put me into a circular loop. Now you should have code and tasks all in the same project.
There is only more thing that needs to be configured to really tie all the pieces together: the Mylyn integration that I mentioned at the beginning of this post. Open your Eclipse Preferences and navigate to "Mylyn->Team".
Change the "Commit Comment Template" to this:
[s:teamforge, t:${task.key}] ${task.notes}
This syntax will automatically add the ID of the task currently being worked on into the commit log message for the repository and Codesion will create an association between that task in TeamForge and the SVN commit. Adding ${task.notes} will also tell Mylyn to include any notes added to the task into the commit message.
When I open a task (by clicking on the Artifact number on the task board or on the task list) I then activate the task by clicking the bluish-purple circle in the upper left corner and make any changes directly to that task, including adding some notes for my commit message.
Last but not least, I simply commit my code changes back to my Codesion repository and let Eclipse, CollabNet, and Mylyn take care of everything else for me.
Just like that, my commit message is fully populated for me in the proper Codesion format with the correct task id and all of my notes. I don't have to add anything else.
I hope this helps to automate some of your project workflow and create more traceability between the work done within your code and the tasks assigned to you.
