Mastering the Eclipse Toolset: Change Sets

“An apprentice carpenter may want only a hammer and saw, but a master craftsman employs many precision tools. Computer programming likewise requires sophisticated tools to cope with the complexity of real applications, and only practice with these tools will build skill in their use. –Robert L. Kruse, Data Structures and Program Design

Eclipse is one of the most sophisticated toolsets ever offered to developers. Its plethora of available tools can eliminate many headaches from a developer’s day. Unfortunately, there are days when headaches still occur, as developers struggle to discover and use all Eclipse has to offer. A great technique for discovering the most useful tools in Eclipse is to watch an experienced developer work. In this post I’ll be sharing my change set toolset knowledge, gained from watching others, in hopes of eliminating unnecessary clicks and frustration from your workday.

The (Small) Cost of Change Set Support

Contrary to many spammers’ beliefs, everything in life has some costs, and the advantages offered by Tasktop Dev and Mylyn’s change set tooling are no exception. To enable the benefits of the change set tooling you will need to:

1. Click the “Activate” button on a task before starting that task
2. Click the “Deactivate” button when finishing a task

Once you develop the habit of working in this way (see Task-Focused Tutorial for details) then you will be able to:

1. Navigate from any line of code to the relevant task or bug report
2. Review your teammates changes and view only the files that changed
3. Quickly erase changes made for a given task (Undo at the task level)

The following sections will walk you through different aspects of the change set tooling and show you how to maximize your benefits.

Change Set – ..the set of changes made in a single commit.

http://en.wikipedia.org/wiki/Revision_control

In (hopefully) all software development organizations there is repository for storing your code. For Eclipse users this often means using a Software Configuration Management (SCM) system like CVS or Subversion. When working with an SCM developers usually download the entire code base and then submit updates to this code base in the form of change sets, or a set of files that they have changed.

Tip #1: Tracking Current Changes

Tasktop Dev and Mylyn automatically track the changes that you make as you work on a task, thus automatically creating a change set. You can view all of your current changes by opening the Synchronize View. Be sure to toggle the view model (circled below) until you are viewing changes as change sets.

Viewing changes using the Synchronize View makes it easy to quickly review others’ changes and to manipulate your own. The left pane in this example contains four change sets, one of which is expanded.

As you make changes when working on a task a new change set will be created and shown in the Synchronize View. Thus, when you have completed a task it is easy to commit only the relevant code. Open the Synchronize View, right-click on the change set, and select Commit. Occasionally you will work on a task and then abandon it, either because it seems infeasible or because priorities have shifted. In this case it is easy to remove all the changes you’ve made for that particular task by selecting the change set in the Synchronize View and selecting Override and Update (see screenshot above).

Tip #2: Connecting Commits with Tasks

All source code was written for a reason, but when viewing a particular file the original reasoning is not always clear. Fortunately, when using Tasktop Dev/Mylyn tasks to track your work you can easily connect every line of code with the reason it was changed. This connection makes interpreting individual files easier and reviewing changes after-the-fact possible.

Creating and Configuring Automatic Commit Messages: When using tasks to track your work meaningful commit messages will be attached to every commit that you make. When you attempt to commit a set of files Tasktop Dev/Mylyn will automatically populate the commit dialog with tasks that were active when you changed these files.

In the above example you can see that the file AbstractTaskAssociation.java is the only file in this change set and that bug 5256 was active when it was changed. To establish a connection between this change set and your task simply do not erase the commit message. Later, when viewing the changed lines in file AbstractTaskAssociation.java it will be easy to trace back to the relevant task (discussed below).

From Code to Task: Enabling the automatic commit messages allows your team to trace from any line of code back to the last task that changed that line of code. Starting from a source file, use the context menu in the editor to select Team -> Show Annotations. This will populate the gutters of the editor with a line to task mapping. In the example above you can see that method isValidUrl was last changed to ensure that URLs did not contain spaces. To open the relevant task use the context menu in the History View (automatically opened for you) and select Open Corresponding Task.

Viewing the task has several advantages for understanding a particular line of code.

1. The description and comments of the task often have relevant information, including design decisions or problems that were encountered.
2. The task context (if available) will allow you to interpret the changes as a whole.
3. The task contains information about the people involved, including those that did not make the commit, whom you may want to discuss the code with.

Tip #3: Sharing Changes with the Team

In the open source community developers often need to submit a patch, essentially a change set, to address a particular bug. The developer in charge of that component will review the patch and either apply it or ask for improvements. The process of creating, reviewing, applying, and reapplying a patch is painless with Tasktop Dev. When a developer is creating a patch he (or she) usually begins with an up-to-date workspace. He then changes a few files to implement the fix. Once complete, he can use the Synchronize View to create the patch (left), which he can then attach to the bug using the Task Editor (right).

Sharing Changes with Your Team

Once the patch is attached to the bug he can revert to a clean workspace by Overriding and Updating his change set in the Synchronize View. If the patch is not approved he can, directly from the task, reapply the patch (below) and begin working on the necessary changes, again submitting an updated patch to the bug.

The developer reviewing the task also has the advantage of reviewing the changes in his workspace instead of reviewing a text file. He can apply the changes to his workspace and download the context (below) so that only the relevant files are shown in his package explorer. Reviewing changes in this way allows the developer to focus on only the changed code while reviewing, testing, and applying the patch.

Attach Your Context!

In this post I’ve shared with you the toolset that Eclipse and Mylyn/Tasktop Dev offers for change sets. There are many opportunities to eliminate extra clicks and improve collaboration by taking advantage of this tooling. A great way to start using this tooling is to activate your Mylyn/Tasktop Dev tasks and attach your context when submitting a patch. Attaching your context when submitting a patch makes it easier for other developers to review your patch, actually increasing its odds of being accepted.

Next time that you submit a patch… do not forget to check “Attach”!