Don’t Break the Build: A Developer’s Guide to Care-Free Commits

Summary: Learn how to submit the right files for a given fix every time, even when working on multiple bugs concurrently, avoiding the sin of breaking the build.
Applies to: Tasktop Dev Pro, Tasktop Dev Enterprise, Eclipse Mylyn
Supported Connectors: JIRA, Rally, CollabNet, Bugzilla
Supported SCMs: CVS, Subversion (SVN)

Developers who break the build must wear the hat of shame.
Photo courtesy of seeb’s Photo Stream

In most development circles breaking the build is a serious offense, with good reason. As other programmers check out the broken source code their progress becomes blocked, as they can no longer compile (and thus test) the software. The cost of blocking an entire development team is so large that many shops have resorted to shame tactics, forcing offenders to wear embarrassing hats or shirts. Fortunately, Tasktop Dev can significantly reduce your chances of obtaining a new headpiece by automatically tracking changes related to each task.

Common Problem: Committing Too Much, or Too Little
One of the major causes of build breakage is committing the wrong set of files for a given fix. These types of problems reduce to 1) committing files that are unrelated to the fix and 2) omitting files that are relevant to the fix. Either case can easily cause a broken build as a committed file can reference a new method or field in an uncommitted file. While it might sound easy to track the changed files for a particular task, developers that try to do this manually face several challenges:

  1. Tracking individual tasks can exceed working memory – For some tasks developers must change more than a few files. For any task that requires changes to more than seven files the developer must remember a list of files that exceeds many people’s working memory capacity.
  2. Multi-tasking requires multi-tracking – Developers work on more than one task in parallel, and thus must track files for each task. If a developer is working on five tasks in parallel, changing as few as three files per task requires remembering 15 files, in addition to the file to task mapping.
  3. Tracking changes can span days, or even weeks – A particular development task can often become blocked after the developer has already changed several files. As the developer waits days or even weeks for the task to become unblocked his memory of the changed files will likely start to decay.

Tasktop Dev can help you avoid these problems. It can automatically track the files you change for a given task, freeing up your working memory. Tasktop Dev eliminates the multi-tasking problem as well, tracking changes for each task separately. Finally, it avoids the memory decay problem.

Solution: Automatic Change Set Management

In order to use Tasktop Dev to automatically manage your change sets you only need to activate tasks as you work on them. To activate a task you can click on the icon next to the task in the Task List.

Task List with active task

In this example Bug #59, “Cannot read emails from Thunderbird” has been activated, as indicated by the icon and the bold summary in the Task List.

Once you’ve activated a task continue to edit, compile, debug as you normally would. The only changes to your existing workflow are when you finish a task. Once you finish a task open the Synchronize View and toggle the model mode, as shown below:

Change Sets with Toggle Model Highlighted

Once the model is changed to show change sets you’ll notice that all of your outgoing changes have been arranged by task (i.e., a change set has been created for each task). Similarly, all incoming changes are organized by task. Below the same set of changes is presented in the Java Model Mode (background) and in Change Set Mode (foreground). Many people consider it much easier to interpret the changes in Change Set Mode because all of the changed projects and files for a given task are grouped together in that change set. In the Java Model Mode the changes are listed per project, and thus any changes involving more than one project are scattered throughout this list. Additionally, any project that contains changes for several tasks groups the changes together into one change set.

Change Sets in two different modes

To commit your changes, select the current task, which is bold, and use the context menu to commit the changes. Tasktop Dev automatically fills in your commit comment so that others know which task your changes correspond to, and can navigate from the committed code to the corresponding task.

A commit comment automatically filled in by Tasktop Dev.
In the above commit dialog the commit is for the task 5256 and the automatically generated comment includes the task status, task type, task ID, task summary, and, on the next line, the task URL. The format of the automatically generated comment is configurable, and you can change it to match the format that your team prefers (Window -> Preferences -> Task -> Team) by adding the completion date, the assignee, etc. or rearranging the order of the template. For this commit only one file is involved, the AbstractTaskAssociation.java file, which is shown below the commit comment.

It's not nice to break the build

Allowing Tasktop Dev to manage your change-sets for you has several advantages. First and foremost, it ensures that you are committing the correct files for a given task. Although it is still possible to break the build* the chances of breaking the build are significantly reduced. Additionally, if you abandon a task prior to committing your changes for any reason, it is easy to revert the changes for that task by selecting “Override and Update” for that change set. Furthermore, all of your commits are automatically commented with a link to the relevant task, so others in the team can more easily interpret your changes. If all team members are using change sets to commit their code it can improve collaboration. For instance, a colleague can commit a fix and ask you to test it. Because the incoming changes are organized by change set you can select the fix of interest and just update that change, isolating the code of interest.

Tasktop Dev’s change set management can reduce your mental burden during programming, allowing you to focus on the important problems at hand by tracking the details for you. If you’d like to get started with automatic change set management, download Tasktop Dev.

* If you work on two tasks in parallel that involve changing the same file it is possible to break the build by committing one of the tasks without committing the other.