Tag Archives: bugs

Developing with branches

There was recently some discussion on the Koha mailing list about how “branches” fit into the development process. I replied with a description of how I use branches in my development process, and this post is an expansion of that.

In my discussion of Koha’s bug-reporting process I mentioned that a developer who wants to work on a bug will “accepts” a bug in Bugzilla before beginning work on it. There is a lot more to the developer’s workflow going on behind the scenes. I’ll describe what my process is.

When I first begin to work on fixing a bug, I create a “branch” in the git version control system. When I do so git creates a separate working copy of the main branch, “master.”  This copy is of the very latest version of Koha available. I create a separate branch for each distinct change I want to make to Koha. That change might be defined as a bug fix for a particular bug, or a new feature. The changes to each branch might include modifications to many different files, but the changes should all be related to that one subject.

It’s vitally important that I keep my branches clean and separate from each other because the Release Manager is relying on me to make it easy for him to apply and test my patches. If I submit a patch that covers more than one “subject,” that makes it all the more difficult to test it properly. If I introduce a bug to one aspect of my update, the whole patch may have to be rejected. Keeping things as simple as possible makes it easier for everyone.

To see how this looks in my workflow, here’s a selection of my current working branches:

ip-Bug-3125-IE-selects-2010-05-18
ip-Bug-4173-restricted-status-2010-03-18
ip-Bug-4901-Zotero-subtitles-2010-07-09
ip-hold-interface-test-2010-07-19
* master
ps-Bug-2307-calendar-i8n-2010-07-13
ps-Bug-2704-440-Display-2010-07-13
ps-Bug-2981-alternate-solution-2010-05-18
ps-Bug-3459-topissues-2010-06-29

When I first sit down to work I create a branch with a prefix “ip-” for “in progress,” give it a short title and bug number if I have one, and add the date I started working on it. You can see I might have quite a view branches in progress at a time. This might be because I’m working on a big update which is time-consuming, or it might mean I’m stumped about what the solution is.

Each time I sit down to do more work on a bug I switch to that branch, download the latest updates which have been submitted and approved on the master branch, and tell git to “rebase” my branch. The rebase process merges my changes with the latest updates. If there are any problems with the merge git will warn me and ask me to make manual changes. Usually the process is automatic. I do this every time I sit down to work on an in-progress branch. This ensures that the changes I’m making are compatible with the latest version of Koha.

Once I have finished my work I check it and test it as carefully as I can. I make sure I’ve rebased against the very latest update in git, and I submit a patch. Submitting a patch takes the changes I’ve made and distills them down to a single text file which can be “applied” by the Release Manager or any other Koha developer to their own git installations. I also attach a copy of my patch to the bug report, if there is one, as I described in my bug reporting post. This is another way to get the patch out into the open where others can review it and test it.

After I’ve submitted a patch I rename the branch I was working on with “ps-” for “patch sent” and keep the branch until my patch is approved (fingers-crossed).

All this is on my computer in a virtual machine, so in my case I’m not being open as I might. If I had the resources to work on a real server, or if I kept my work on a service like GitHub I could share all these branches with everyone, from the time I first started working on it to the time my patch was submitted.

If some time has passed and I see that my patch from one of my “patch sent” branches hasn’t been approved I’ll switch to that branch and rebase: I’ll tell git to grab the most recent Koha commits and merge them with the changes in my patch. If not too much time has passed, or the files I changed haven’t been worked on by others the rebase will be successful and I’ll know I’m still on track. If not I might have to manually make changes to my original commit so that it fits in again with the work others have been doing. If manually merging was required, that tells me the Release Manager would have to do the same. I should consider resubmitting a revised version of my patch which can apply cleanly to the latest version.

Keeping all my “patch sent” branches intact until my patch has been approved is important to my workflow because it’s the easiest way for me to keep track of what has been approved and what hasn’t. I can see at a glance which patches of mine have not been approved. If it’s been a while, I might try to find out why not. If there was a problem with the patch I might be able to revise it to the RM’s satisfaction.

I can’t submit a patch and expect it to automatically work a month from now, a week from now, or even a day from now. I’m responsible for keeping up.

I’m not a git expert, and I’ve had lots of help and advice along the way to get me to this workflow. It works really well for me, and I hope it works as well from the point of view of our Release Manager and fellow developers.

Koha bugs workflow

As the Koha project has grown our workflow has evolved to meet the demands of a wider pool of developers. We’re better today at collaborating thanks to Git, our version control system. We’re better at communicating with each other through the Koha wiki and Koha’s Bugzilla database. It has helped a lot that we’ve worked to establish some consistent steps to handle both bugs and new features.

Filing a bug report

When you’ve discovered a bug in Koha the first stop is Bugzilla. Bugzilla is an open-source bug-tracking system developed by the folks who brought you Mozilla Firefox. We have our own installation of Bugzilla, generously hosted on a donated server. Anyone can file a bug, whether you’re a Koha developer or a Koha user.

If you find a bug the first step is to report it. Even a developer intending to immediately fix a bug should file a bug report. Doing so will mean others won’t duplicate your efforts in isolating the bug. When you file a bug report Bugzilla will offer to assign the bug by default to the person who has volunteered for bugs of that category. For instance, I am assigned by default any OPAC bugs. That doesn’t mean I’ll be able to fix them all, but I’m notified of each one and I can always reassign them if I find they’re beyond my capabilities.

You can also assign the bug a “severity” setting. If you’re not sure, use the “normal” severity for bugs, and “enhancement” if you’re asking for a feature to be added. There are brief descriptions of Bugzilla’s severity levels for review if you’re not sure how to classify something.

There are much more detailed bug reporting guidelines on the Koha Wiki.

Now the bug is in the database. With any luck, anyone else who discovers the same bug will search Bugzilla first before reporting it. If you find an existing report for a bug you’re experiencing, review it to make sure all the pertinent details are there. Feel free to leave comments expressing in specific terms how the bug is affecting your library’s workflow. Understanding the impact of a bug might help others prioritize efforts to fix it.

What happens to your bug?

What happens to a bug report after it gets filed? If the report was filed without any plans to address it (that is, if you’re not a developer filing the bug, with plans to fix it right away), nothing may happen for a while. Ideally the default assignee of the bug will review it and take some action if necessary: Correcting the bug’s severity, asking clarifying questions, reassigning if necessary. Unfortunately there is no guarantee that anything will happen with a bug report once it is filed. If no one else is affected by (or cares about) the bug, there won’t be any incentive to fix it. Developers are often working on projects assigned to them by their customers, and if they’re not getting paid to fix a particular bug they may not choose to work on it.

Your bug finds acceptance

If someone decides to work on your bug report, the first thing they should do is “accept” the bug in Bugzilla. If the bug isn’t already assigned to them, they edit the bug to assign it to themselves and update the status of the bug from “New,” the default for all new bugs, to “Assigned.” This tells anyone browsing Bugzilla that someone has agreed to work on the bug. Careful use of bug assignment and the use of the “assigned” status helps prevent duplication of effort: I won’t spend time working on a bug if I think someone else is actively working on it already.

If the developer who took on your bug discovers a fix for it, the next step is to submit a patch. A patch is a special file which can be understood by our version control system. Just as a patch on a piece of clothing is just a small piece of cloth to fix a hole, a software patch is just a small piece of code which can be applied to a whole file (or even multiple files). The patch includes instructions to add certain lines or remove certain lines of code.

The developer who has come up with a patch will do two things with it: First, the patch gets submitted to a special Koha mailing list for all Koha patches. Koha’s Release Manager monitors this list and evaluates each patch and evaluates it for inclusion in the next version of Koha. The second place the patch will go is into the Bugzilla bug report. The developer will attach the patch to the bug report so that others can see that a patch was submitted and maybe review the patch themselves. Since the patch file is easily understood by the Git version control system, anyone running an installation of Koha from a Git repository can apply patches and test bug fixes. A bug in Bugzilla which has has a patch filed for it will be marked with a special priority, “PATCH-sent.”

Your bug found acceptance, but what about the patch?

Galen Charlton, the Koha 3.2 Release Manager, has the task of evaluating each patch that is submitted for inclusion in 3.2. He reviews patches, tests them, and approves them if he finds them worthwhile. If a patch refers to a specific bug report, Galen will usually also update the bug report with a note that the patch was “pushed.” If a patch doesn’t seem to work, or if it includes mistakes which should be corrected before inclusion he will let the patch submitter know so they can rework the patch.

Right now we’re getting so close to the release of 3.2 that we’re under both a “feature freeze” and a “string freeze.” A feature freeze means that no new features are being accepted for inclusion in 3.2: only bug-fixes. Rejecting new features at this point in the process reduces the possibility that major new bugs will be introduced. The “string freeze” means that patches submitted for inclusion in 3.2 should no include changes to any text in the interface. These text strings must be painstakingly translated. The Koha translation-tracking system Pootle lists 63 different languages which have at least begun to have translations done. Putting on a string freeze means that translators preparing for the release of 3.2 will have a fixed target.

The patch for your bug made the cut. It’s going into 3.2!

You reported the bug, so your job isn’t done yet. It’s time to test the fix. Update your test installation and try to follow the same steps that led to the bug before. Is the bug still there, or is something still left undone? Then update the bug and explain what you found.

On the other hand, if you find the bug has been fixed then you can mark it as such in Bugzilla. Change the status of the bug from “Assigned” to “Resolved (Fixed).”

Congratulations, and welcome to the team.