2001 December 10
This is the second of a series of articles on how you can help contribute to OpenOffice.org--the product and the project. In the previous article, we focused on the mailing lists and how to subscribe to the more popular ones; this article deals with our bug and issue tracker, IssueZilla.
What's an issue tracker? And, for that matter, what's an issue? And why "IssueZilla"? First things first. An issue tracker records the history of an issue from filing to resolution. An issue is not exactly a euphemism for a bug; rather, it is simply a more inclusive term. It schedules and tracks not only bugs (defects, mistakes, nasty surprises), but also tasks, enhancements, and the like. We define issues, bugs, and how to use IssueZilla, in some detail on our "Got Issues?" and "About Issues" pages. This present discussion does not supersede our already extensive documentation on IssueZilla; it only complements it.
IssueZilla, our issue tracker, is a proprietary derivation of mozilla.org's justly famous and popular Bugzilla. CollabNet improved the code and updated the package and user interface. But the basic structure is similar, and many of our documents on IssueZilla still use edited versions of Bugzilla's open-source documents, so if you are familiar with Bugzilla, you should be right at home with IssueZilla.
With IssueZilla, the filer and assignee and anyone else associated with the issue is notified of the issue's progress. They can add attachments, too, meaning that documents can be shared among several individuals (or many individuals). Project managers, in particular, will begin to see the great advantage of this setup and why it is so superior to email. Instead of sending off messages which stand an excellent chance of being buried, the filer can file an issue which will be listed every time the assignee (the person to whom the issue has been assigned) logs in and checks her issues. It won't be lost, or abandoned. And when it is resolved, people can check it and confirm the resolution.
For these reasons--because it makes collaborative project management actually manageable--we urge OpenOffice.org community members to use IssueZilla.
Say you download the latest build, start using it, and find a problem--a bug or "defect"--or want to suggest something you think would improve the code (an "enhancement"). What we would like is for you to file an issue describing this and any other problem you find or suggestion you wish to make. The reason? OpenOffice.org is an Open Source project and lives or dies on its community participation. The project leads depend on the community to test, prove, and improve the program. And who is this community? Basically, any user of OpenOffice.org, including, of course, the project leads and their team members, but also endusers. (In fact, it was Linus Torvalds' brilliant observation that in Open Source projects the distinction between an producer and consumer--between a developer and enduser--vanishes, for all are committed to working on the product and project.)
Say then you want to file an issue. You must first register, if you are not already a registered user of OpenOffice.org. Only registered users can actually file issues, though of course nonregistered may certainly submit issues via email to the relevant email list and ask someone else, who is a registered user, to file an issue. But because that process makes others do more work we prefer that community members register and use IssueZilla.
It's easy--but also a little confusing, and in the sections below I will sketch out the process of using IssueZilla. Again, as I mentioned above, this discussion is not a step-by-step guide to using IssueZilla--we already have that--it is rather a general guide to what is available. Much of my discussion derives from our "About Issues" document and from the SourceCast help material on IssueZilla. Readers are urged to refer to those documents.
First things first: register with OpenOffice.org, if you have not already. Then log in. Once you have logged in, you will be able to see the "My Issues" link on the left navbar. Click on it and view the list of issues assigned to or by you. For the most part, filing out the IssueZilla form is not terribly difficult, but there are some choices to make, among the most important being the component to file the issue under. The list of components does not fully tally with the list of OpenOffice.org projects, but for the absent projects, you can file an issue against the www (web) project, and the owner of that project will direct your issue to the appropriate spot.
Why is it important to choose the right project for your issue? Because OpenOffice.org works on a per-project basis, meaning that an issue with the "framework," for instance, should be handled by that project. Assigning the issue to the default owner of that project's issues will go a great ways to ensuring that the issue is actually worked on.
Once you have chosen the component, you can fill in the form. For clear instructions, again, please see the "Issue Writing Guidelines" page, which walks you through the process in some detail.
By the way: You can also file issues for things having to do with the general website, not the project or code. For instance, if you notice a broken link, a misspelling, or are unable to use the mailing list--anything like that--file an issue and assign it to the "www" component.
Assuming you have correctly filed an issue, the next step is up to the person to whom the issue has been assigned, often the project lead, or at least the person responsible for the module. That person is notified of the issue via email; he must then accept the issue, which signifies his receipt of the notification. It's then up to the assignee to act on the issue.
Depending on the priority level you have attached to the issue, the assignee will act on it with greater or lesser urgency. But let's say it's a P2. In that case, the assignee will probably deal with as soon as he can. If he can resolve it (fix it), he will signify as much and close the issue (which remains in the archive of issues filed). But there are other possibilities: the issue may not be resolvable, or may depend for its resolution on a network of other issues. For a description of these possibilities, please see the "Got Issues" page.
In any event, notification of the progress made on the issue will be sent to the email address you used to register with OpenOffice.org. Included in this email will be the URL for that particular issue; depending on the setup of your email client, clicking on it should take you to that issue. But to comment further on the issue you must be logged in first.
At some point, if you become active in OpenOffice.org, you will undoubtedly have many open issues. These can be worked on not just by you, or by your assignees, but also by others, who have been brought in to resolve them. In short, opening an issue with IssueZilla means opening the door to true collaborative work.