Don’t Break the Build: A Developer’s Guide to Care-Free Commits
, October 7th, 2009| 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 Pro, Eclipse Mylyn |
| Supported Connectors: | ClearQuest, ScrumWorks, JIRA, Rally, CollabNet, Bugzilla |
| Supported SCMs: | CVS, Subversion (SVN), ClearCase (coming soon) |
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 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:
- 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.
- 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.
- 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 can help you avoid these problems. It can automatically track the files you change for a given task, freeing up your working memory. Tasktop 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 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.
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:
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.
To commit your changes, select the current task, which is bold, and use the context menu to commit the changes. Tasktop 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.
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.
Allowing Tasktop 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’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 Pro.
* 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.
October 7th, 2009 at 9:12 am
The real, underlying problem that needs addressing here is better addressed by continuous integration and decentralized version management systems.
The problem is inherent to any kind of centralized repository where people can just dump any change. Fact: people make mistakes. Without control, that leads to broken builds. Bureaucracy (do this or that or you get to where the stupid hat) or tools that automate parts of the bureaucracy are not a real solution, they just address the symptoms. Worse Bureaucracy is a workaround. It’s inefficient. It’s annoying, it takes time. You constantly have to ‘educate’ people about it. Lazyness is a sign of intelligence, something to value. Tools that allow intelligent people to relax and be lazy are good.
With decentralized version management, committing changes from push to pull. So if you set up some continuous integration server that pulls changes from a untested repository (or some email server), that tests the changes and pushes them to a tested repository, this problem is solved. You commit/email your changes to untested. Nobody but the integration server pulls from there. Only changes that pass compilation + unit tests get pushed to tested. Failing changes are rejected and automatically removed from untested. Everybody pulls changes from tested that have passed the test suite and are guaranteed to compile. Always. You break untested, it’s your problem: as it should be.
You can layer this of course and insert more repositories with more and more checks and balances between them. Great for scaling up development to multiple teams.
Now if I’d only be able to convince my colleagues to ditch their 20th century version control technology and move their ass into this century …
October 7th, 2009 at 1:26 pm
Jilles,
You raise some great points. I totally agree that better version control and continuous integration practices are the right way address the underlying problem of broken builds. Although builds are only one developer’s problem in the scenario you describe, grouping modified files by task still helps developers avoid having their commits rejected from untested. This approach also helps developers know which files to revert or update from tested on a per-task basis when working on several things at once. Keep in mind that the tooling makes the task to file mapping explicit but doesn’t actually enforce work flow. Another way Tasktop and Mylyn can help nip problems in the bud before committing is by quickly running only the JUnit tests that test the code changed as part of a given development task.
Good luck convincing your colleagues to join this century!
October 7th, 2009 at 7:41 pm
Developers working on major changes on 5 different things *seems* to be wrong. Working on small chunks that enable developers to check in early, check in often is often a good idea
Also DSCM that keeps track of local branches helps heaps in such cases — it is not always true that 5 features require 5 different sets of files; there would always be something that is common. Git for example allows for me to check in parts of a file into a commit.
Mylyn is a really great way to solve the multitasking issue, and I love this aspect of mylyn when it helps ease switching context — but working on multiple features at the same time and not checking in into source control seems to be a very wrong thing to do.
October 7th, 2009 at 10:31 pm
It sounds interesting. If you plan to support ClearCase soon, you’d better know that it’s much more necessary in Base ClearCase rather than UCM ClearCase. In UCM, you can manage your tasks (activities) quite tightly, and if you integrate your environment with ClearQuest - even more.
October 8th, 2009 at 1:17 am
Great post, and good motivation for people to get on board with Tasktop.
I presume there’s one case that Tasktop can’t help with. That would be where I’m working on two tasks but both will involve a common class. I’m guessing that by committing from Task1, changes I made to the class while in the context of Task2 will get committed too? This is the case where the developer needs to use the working memory
James
October 8th, 2009 at 3:22 am
I’m with the other commenters who feel that working on multiple uncommitted changes, and making partial commits, is wrong and dangerous, no matter how much support Mylyn gives you for tracking changes with respect to tasks.
The problem is that my local build will always see all the changes I have made, irrespective of task, and therefore if I only check in part of those changes there is a substantial risk of breaking the build even when my local build is green.
A better solution is a version control system like Git, that allows quick switching between local branches and ease of merging across those branches.
Oh and another thing, in your bug list snapshot: “British spelling used on homepage” is not a bug, it’s a feature!
October 8th, 2009 at 2:17 pm
I would agree with Ketan and Neil that having uncommitted changes for more than one bug or feature is best avoided. Unfortunately a lot of developers find themselves forced into this situation on a regular basis, which is why tools like Eclipse and ClearCase UCM provide manual facilities for tracking change sets. One of the main advantages of Tasktop’s change sets is that Tasktop automatically creates change sets, whereas developers were previously forced to construct them manually.
For those that are lucky enough to have a development process and tools that make it easy to work on one thing at once, you will still get the benefit of the automatic commit comments, automatically generated change sets, etc.. We’ll have more on these further advantages of Tasktop’s change set management in an upcoming post…
October 10th, 2009 at 4:28 pm
How do you handle the situation in which the code you commit gets compiled on 50 distributions of linux with god knows what compilers?
Still thing breaking the build is a shooting offense?
November 7th, 2009 at 4:03 am
Speaking about better continuous integration systems: take a look at TeamCity. It offers pre-tested commit feature to solve the 5 o’clock problem and it does not require decentralized SCM for this: http://www.jetbrains.com/teamcity/delayed_commit.html
Moreover while the build with non-committed changes is running you can modify the same files.
November 15th, 2009 at 10:27 pm
Nice hat!
Don’t be so hard on yourself. It happens to us all