[Courses] [Tools] Coordination tools: bug trackers and mailing lists

[Mary]

This post is the third 'lesson' in the Participating in Free Software
LinuxChix course. You can find previous lessons at
http://www.linuxchix.org/content/courses/tools/ . Questions and
discussion are welcome, please make sure the string "[Tools]" is in the
subject of your mail.

In this section of the course I'm giving an overview of This lesson
describes two ways of collaborating on Free Software work: bug tracking
software and mailing lists, and typical ways of using them.

This is the first lesson with "homework". At the end of the section on
bug tracking software are a couple of tasks you can do to check your
understanding of the lesson. Feel free to post your solutions back to
the list immediately: there are multiple solutions. You can also ask for
help with them.

-- Bug tracking software --

Software projects generally tend to have pretty complex todo lists. A
number of specialised tools have developed to track these todo lists,
these are known collectively as "bug trackers" or "issue trackers".

The typical usage of a tracker is this:

 1. a person, sometimes a developer but most commonly a deeply involved
    community member such as a tester or enthusiastic user, files a new
    bug or issue.

    Sometimes this user will also file a "patch": some code that fixes
    the problem. This is unusual but valued.

    Bug trackers often track bug status, these bugs are often in status
    "new" or "unconfirmed" or similar.
    
 2. a person, usually a developer but sometimes a tester, takes the
    report and analyzes it. They analyze its status: maybe they can
    replicate the problem, maybe they can't. Perhaps the 'problem' that
    someone is complaining about is actually a deliberate choice.
    Sometimes, the bug has already been fixed in a newer version of the
    software. Sometimes the problem is extremely urgent: perhaps it is a
    security problem in the software, or the software is broken in a way
    that will affect a lot of users badly (eg, saved files are
    corrupted). Sometimes the problem is rarer and less urgent (eg
    saving a file sometimes takes 30s, but only in a particular set of
    rare circumstances). Sometimes the problem has already been
    reported. This process is known as "bug triage".
    
    The holy grail of bug reporting is the ability to file bugs that
    contain a useful, reliable, step-by-step procedure for getting the
    bug to happen all the time. This is a lot of work for the bug
    reporter, but bug triagers and bug fixers really appreciate it,
    because they can get straight to work without needing to go back and
    forth with you several times about the nature of the problem. I've
    collected hints for bug reporting at http://buglinks.org/

    After triage, a bug is usually in a "confirmed" or "assigned"
    (assigned to a developer to fix) status. Rejected bugs may be marked
    "not reproducible" or "duplicate" (of another bug) or "invalid"
    (it's not a bug, it's a feature, a misunderstanding or a bug in a
    different piece of software).

 3. a developer analyzes the problem and determines its source. They
    then decide whether they can fix it (if they can't replicate the
    problem reliably, this is a hard task) and whether they are willing
    to. If they are they will fix it and close the bugs.

    After a developer fixes the bug it is marked "resolved" or "done".
    Bugs rejected by developers might be marked "invalid" or "wontfix".

Almost all bug trackers are web applications, ie they are websites,
accessed through a browser. Bug titles and descriptions are entered into
a form and submitted.

Typically, bug trackers let you track the following things about a bug:

 1. Title: a short description of the bug

 2. Comments: a longer description of the bug including steps required
    to make it happen. Developers will then use comments to solicit more
    information, and in some bug trackers also to discuss the possibly
    solutions.

 3. Status: the state of the bug. Typical values are: new (just
    reported), assigned (assigned for fixing), resolved or fixed,
    invalid and duplicate.

 4. Cc list. This is a list of people who are following the bug, who
    will be emailed whenever the bug is updated by anyone.

 5. Attachments. These might be patches, screenshots of the problem in
    action, a corrupted saved file and so on.

They may also let you track other things, such as bug keywords, or time
estimations.

Usually although not always bug trackers for Free Software projects are
public and publicly editable. You can add bugs and update bugs simply by
registering on the website. Most typically a bug reporter will simply
report the bug, and then only edit the bug further when asked for more
information. This request is very common: the developer might ask
whether the bug is seen in a certain other set of circumstances ("does
it happen when you press Ctrl+s to save rather than using the menu?") or
whether a new release of the software fixes the bug for the user.
Sometimes they might change its status (such as when a developer claims
it is fixed but they are wrong) but usually this is the job of the bug
triager and the developer (in small projects, these are usually the same
person).

Bug reporting can be surrounded by a surprisingly opaque set of
etiquette for newcomers. The problem is conflicting user and developer
attitudes. The user has typically and understandably expected the
program to "just work". It's very frustrating when this doesn't happen,
and they have good reason to regard bugs they found as both annoying and
urgent. Developers on the other hand have typically sunk a lot of time
and thought into the development for usually no monetary gain and almost
always very little thanks. It's not uncommon to get moderately or even
extremely rude bug reports and this can aggravate developers quite a
lot.

Distributions *also* have bug trackers. This is because they customise a
significant amount of the software they distribute before bundling it up
in a distribution. They also may support particular versions of it that
the original authors no longer support (having moved onto new releases).
It's therefore usually a good idea to report bugs found in distribution
software to the distribution rather than to the original authors of the
project. The distribution will fix it themselves if its a problem with
their customisations, or they will pass it onto the original authors.
This also means that the distributions, which often have more resources
(including paid employees for some) than original authors, can do the
bug triage work before passing it on.

Bug tracking software includes:

 1. Bugzilla, the most common Free bug tracking system. This is a web
    based system.

 2. Debbugs: Debian's bug tracking system. This has a web interface but
    you report and update bugs via email.

There are some other less commonly used bug trackers and there are also
some non-Free bug trackers used by free projects, often associated with
Free Software portals like sourceforge.net, which has its own bug
tracking software which Sourceforge projects can use.

-- Homework for bug tracking --

Remember, you can ask if you need help with the homework!

1. This homework will use the Ubuntu Bugzilla. This bugzilla is located
   at https://bugzilla.ubuntu.com/ To answer these questions, post bug
   URLs to this list.

   1.1 Find a problem in firefox.

   1.2 Find a bug that has been filed but not confirmed. (In the Ubuntu
   Bugzilla, these are bugs marked NEEDINFO , you'll need to face down
   Bugzilla's Advanced search to search by status.)

   1.3 Find a bug that has been fixed (status RESOLVED).

   1.4 Find a bug that has been rejected (status WONTFIX)

2. This homework question assumes that you use a Free Software
   distribution (eg Fedora, Debian, Mandriva, FreeBSD, Ubuntu...) that
   has a public bug tracker. Ask for the URL if you're not sure. This
   question is more time consuming: remember, homework is not compulsory
   and partial answers are all good.

   2.1 Where is your distribution's bug tracker?

   2.2 Find a bug that has been filed against a piece of software you
       use. (Don't forget, ask if you can't figure out how to search.)

   2.3 See if you can replicate the bug described in 2.2. If not, why
       not? If so, can you see anything missing from the bug report?
       Tell us about it.

   2.4 Think of a problem you have with software on your distribution.
       See if you can find out whether a bug has been filed against it
       yet. (Tell us the search terms you used.) If there doesn't seem
       to be a bug, draft a bug report and send it to us, and we'll help
       you file it.

-- Mailing lists --

Mailing lists are, as you almost certainly know (since this courses list
is one) a central email address that goes to a bunch of interested
people. They're common collaboration tools in Free Software, usually the
backbone of day-to-day development work.

Much of the day-to-day action of medium sized Free Software projects
happens over discussion mailing lists, like this one. For most projects,
major directions will be discussed in email, often to the complete
exclusion of the bug tracker. If you intend to be regularly involved,
you'll spend much more time tracking the mailing list than the bug
tracker.

Using developer mailing lists is not any harder, conceptually, than
using this one. There are a few points to keep in mind:

 1. these lists are often at least occasionally high volume. If you
    intend to regularly participate, make sure you have an email setup
    that will let you deal with, say, fifty to one hundred emails a day
    without taking up enormous amounts of your time. (techtalk can help
    here, but essentially you need to be able to filter your mail and be
    able to skim subjects easily)

 2. unlike developer IRC and chat channels, they're almost always
    business-only. In projects where there is a separate developer
    mailing list, it should be used for development only, not for user
    questions and (usually) not even for bug reports, unless there is no
    bug tracker.

Large projects will generally have multiple lists:

 1. a user list: a list for "how do I do X?" questions, like LinuxChix's
    techtalk but for a particular piece of software

 2. an announce list: a very low traffic list for announcements like
    "there is a new version of our software"

 3. a developer list: a list for development discussion, as above

Very large projects, such as distributions, may have many other lists:

 1. sub project lists, like translation lists, packaging lists

 2. a security announce list, dedicated to announcing the release of
    software with fixed security problems

 3. lists in other languages than the main development language. It's
    uncommon to have many developer language lists, but common to have
    many user language lists

-Mary