Ubuntu Wiki

From The Art Of Community by O'Reilly (http://www.artofcommunityonline.org) by Jono Bacon

Collaborative online projects need a diverse set of supporting tools to flourish. Even the simplest community will use tools for communication, storing work, and sharing information. Many communities build on top of these staples with a variety of tools and facilities for different functions in the community. Different contributors have different needs for their types of contribution. Developers need bug trackers, patch systems, and version control; documentation writers need wikis; text processing tools, and editors; translators need translation tools; testers need test suites; and everyone needs to communicate with each other.

It’s tempting to go out and set up a wide range of tools, but think carefully about how your tools integrate. An efficient and integrated set of tools will be far more pleasurable to work with than a completely disconnected set of tools.

Integration offers a range of opportunities for collaborative projects. Workflow is the foundation for identifying these avenues of integration. Workflow is a larger process that can contain many individual components.

Avoiding Resource Fetishism

Before we move on to look at some of the technical specifics of different tools, I just want to spend a little time talking about a problem that faces a range of new collaborative communities. The problem looks a little like this:

1. A new community is born around a goal. This goal could be to produce software, change the political landscape, or anything else.

2. The founders of the community set up the communication channels, and some early members join up.

3. Additional tools are required. This could involve a website, blogging tools, technical development facilities, or anything else.

4. Using a website as an example, a discussion kicks off asking which content management system should be used. A long and drawn-out debate starts over which system to use. These debates can drag on for a long time.

I have seen this same scenario happen over and over again. There is nothing wrong with wanting to choose the best tools for your community, but you need to get your priorities straight.

When you set up a new community, one priority is more important than all others: building a team. Your #1 goal is to get people involved. You need to get people inspired to join your crusade. If you don’t attract people and get them up and running and productive as soon as possible, your community will feel like it is treading water.

Debates over which tool to use should be kept as short and sweet as possible. You should seek to establish requirements and gain consensus around a chosen tool as quickly as you can. Always remember that these discussions will garner strong opinions for different tools. You will never make everyone happy, so you need to identify the requirements and pick something as soon as viably possible. The sooner you get your tools up and running and get people focused on doing useful work, the better.

Technical Considerations

Most of this chapter has focused on best practices for assessing optimal workflow for a project, staying detached enough from specific technologies so that it can apply to any kind of community and workflow. The next few pages delve into some technical specifics of particular interest to software projects, such as bug tracking, source control, and collaborative editing. As we cover these topics I am going to deliberately avoid recommending specific solutions or pieces of software. This is because software changes a lot more quickly than books do, and the last thing I want to do is recommend a piece of software that has since become unsuitable for your requirements. Instead, the following pages will advise on some key considerations that you should keep in mind when evaluating which tools you want to use to solve a particular problem.

When evaluating specific software solutions, you should meld the advice here with your current requirements. You should also factor in predicted requirements for the next three years. If you can find a solution that will keep your project productive for three years, you have hit the jackpot. Our goal here is to keep migration to new systems to a minimum: migration is disruptive, complex, and time-consuming.

Bug Tracking

Bug tracking is a critical part of any software project, particularly open source projects. It is one of the core mechanics of how your project works. It should be a central part of your development process and a daily component for each of your developers.

There is a range of bug-tracking solutions available, from those your project hosts (such as Bugzilla) to a third-party-hosted system (such as Launchpad). Bug trackers vary hugely in terms of features. Some are simple, designed for small projects with a small number of developers. Some are hugely complex, infinitely customizable behemoths of functionality.

Before you choose a bug tracker, you should evaluate your requirements. Do you need a simple bug tracker to merely maintain a list of defects in your software, or do you need a complex solution with custom fields, multiple projects, teams, automation, and other features?

A common temptation for new open source projects is to install the most feature-packed bug tracker available. The reasoning behind this is usually “just in case we need those features.”

Whatever your needs, always keep usability as a key requirement in picking a bug tracker. If you use a solution that is too complex, it will annoy potential bug reporters and most certainly annoy those performing triage.

TRANSPARENCY IN BUG TRACKING

You should ensure that your project’s bug tracker is publicly available and that anyone and everyone can access it. As such, you should not restrict viewing the bug tracker to username and password access.

There are many reasons for this:

• There is really no need to restrict bug information if it affects a collaborative community project.
• Users who are experiencing problems can search quickly and easily for information that might help them fix the problem.
• Eric Raymond, a well-known open source proponent, once uttered, “Given enough eyeballs, all bugs are shallow.” Open bug tracking provides an excellent opportunity for community members who are blighted by the same bug to explore, share notes, and possibly even fix the bug together.

The only time I consider a closed bug tracker or private bug reports to be suitable for community projects is when Non-Disclosure Agreement (NDA) work for a specific vendor is occurring, but in a manner that does not compromise the wider project. Bugs that affect the wider project should never be private.

Bug reporting

You should make every effort to make bug reporting as simple as possible. Some projects (such as Ubuntu) embed a link into an application that eases reporting a bug. Ubuntu also uses a special tool called Apport to bundle up debugging information to send to the bug tracker automatically when something crashes. This is a useful feature, as traditionally many developers doing triage would ask bug reporters to enter a series of commands that gather debugging information and add it to the report. Apport (https://wiki.ubuntu.com/Apport) automates this process.

Other projects make the act of reporting the bug on the bug tracker as easy as possible. An example of this is Jokosher, which only asks for a Subject and Description of the bug, leaving it up to the Jokosher triage team to manage the rest of the information. It is important to remember that your bug reporters are unlikely to know most of the requirements for a bug report.

Another project that has taken an interesting approach is GNOME. They produced a simplified frontend to their Bugzilla (http://www.bugzilla.org/ ) bug tracker, and the tracker asks only a few simple questions. It is recommended you keep your own bug reporting frontend as simple as possible.

Bug triage

For each bug that comes into your bug tracker, various decisions need to be made. This includes confirming whether it is actually a bug, asking for additional information from the reporter, assigning the bug to people or teams, and classifying the urgency of the bug.

Triage is a process that your developers will typically need to engage in, and few developers want to spend any more time on it than is absolutely necessary. As such, triage should be as straightforward and painless as possible. Understanding bug workflow, ensuring it is simple and effective, and picking a suitable bug tracker is a critical part of this process.

As your project grows, you likely will become inundated with bug reports. As the bug reports flow in, it is also likely that your developers simply won’t have time to triage the bugs as well as fix them. As such, you may need to consider setting up a dedicated triage team. This, my friends, is a path that you should tread carefully.

Triagers straddle a delicate middle ground in your community. On the far left are your users who have been gracious enough to report a bug in the interests of it being fixed and benefiting the wider community. This is a generous gift on their part, and this gift should be rewarded with the attention it deserves. On the far right side are your developers who have only so many hours in the day to fix bugs. If the developers don’t have enough time to triage the bugs, a triage team is expected to sit in the middle and help ensure the reported bugs are assessed and then routed to the right developers. If this process is successful, all bugs get triaged and the most critical and important bugs get fixed promptly by the developers who have the most appropriate experience in that part of the code base. If the process is not successful, the original users will grow resentful that their bug was “ignored,” and the developers will either drown in bugs (not enough triage), never see bugs (lack of visibility in triage), or focus on the wrong bugs (wrong triage).

Setting up a triage team needs extensive work and resources to be successful:

• Documentation
  • You’ll need extensive documentation about how to triage, what is involved, where to find help, how to respond to users to gather more information, etc.
• Mentoring
  • New triagers need to learn the ropes, and mentoring can help ensure these new contributors get up and running as quickly as possible.
• Events
  • You should organize bug days, meetings, triage events, and other methods of inspiring participation.
• Communication
  • Your triagers should never become an island: they need to be in regular contact with the developers and ensure communication is flowing.

Although it is certainly not impossible to set up a triaging team, and it seems like a fantastic method of contributing, many people often start with triage and grow bored. You should expect this: it is part and parcel of this kind of contribution. Have faith, though, because there will be some people who will join, enjoy, and stick with triage, and you should cherish these contributors and help them to inspire others to get involved.

Source Control

Source control has become an increasingly hot topic in the software development world. Once upon a time, the only real option was a tool called Concurrent Versioning System (CVS). We then had an “easier CVS” come along in the form of Subversion. Since then, we have seen the birth of Distributed Version Control Systems (DVCS), which add even more functionality to source control. DVCS systems make it easier than ever for new contributors to produce features and fixes that can be merged into the main branch. I don’t want to get into a debate about which version control system to use: other resources can provide a far better assessment of that. One piece of advice I do offer, however, is that you should strongly consider some of the integrated tools that exist around these systems. As an example, the Launchpad system integrates tightly with the Bazaar DVCS system and makes tasks such as reviewing merges and viewing changes a point-and-click affair. These kinds of features can be hugely useful with such an important component in the software development toolchain.

Collaborative Editing

Back in the early days of open source, we all lied to the world about documentation. “Want to get involved in open source but can’t write code? Sure you can help! Write documentation!” Back then, if you wanted to write documentation you needed to install a complex menagerie of text processing tools, write your documentation in a markup language, ensure the document properly validated, and then convert the documentation into something the user could read. In a nutshell, it was way too complex.

Most people who write documentation for open source software projects would fall into the category of “power user.” They are technology enthusiasts who are not interested in the supertechnical avenues of programming, but want to help out. Many of these people have good writing skills and a good knowledge of using the software, so the documentation fit is natural.

With Jokosher we wanted to acknowledge this profile of user. As such, instead of focusing on complex text processing tools, we encouraged our documentation contributors to use a wiki. Those who did not know the wiki markup would use the graphical wiki editor. We got some great contributions because we identified the workflow with the type of contributor.