I have been noticing that there are some things that people could be improve when reporting bugs to the Arch Linux bug tracker. So here are some guidelines for what I personally like to see in a bug report. Following these would make finding and fixing the bug less work for me (and I assume other developers).

1. Check the bug is not already reported. This includes checking the recently closed bug reports as your issue may already be fixed and in the process of propagating out to the mirrors. This will prevent multiple bug reports for the same issue, which just creates more work for everyone involved.

2. Provide all information. In particular, do not assume the bug is obvious. What might seem an obvious bug to you may not occur on the developers system, so full information about the packages involved and detailed information on how to replicate the issue is essential. I always like to see at minimum the exact package version involved (including pkgver and pkgrel) and the architecture the bug is occurring on (i686 or x86_64). Do not just report it is the “current version” of a package as that can be useless within a few days on a rolling release distro. The more specific you can be with the package update where the issue started occurring, the easier it is to track down the change that caused it.

3. Stick to relevant information. The list of 50 packages you updated before noticing this bug likely contains the problem package, but there is also a lot of unrelated updates. Reduce this down as much as possible before reporting the issue. More time spent by a packager filtering down to only the relevant information means less time actually fixing bugs.

4. Do not report bugs via links. Providing a link to a forum/mailing list thread that describes the bug is not enough. You still need to provide a detailed summary. This is to keep all information in one place, but also prevents the bug being lost if the link goes dead.

5. One bug report, one issue. Even if you have multiple issues with a package, it is usually better to open a new bug report for each issue. This allows each bug to be closed as it is fixed (which might not be all at the same time…) and prevents issues getting lost among the others. The possible exception to this is when many minor issues with a package are being reported along with a PKGBUILD that fixes them all.

6. Report upstream bugs upstream. If a bug is clearly an upstream bug and not a packaging error, then it needs to be reported upstream. It is fine to also report the issue in the Arch bug tracker (if it is a bug and not a feature request) with a link to the upstream report so the Arch package maintainer can track and apply the fix when available. This not only saves the packager a lot of time (they have many bugs to deal with) but it is also useful for upstream to be hearing the bug information directly from the person experiencing it. The exception to this is glibc who do not accept bug reports from users…

7. Follow up any queries. This is particularly important for bugs that can not be replicated by the relevant Arch packager. The longer a query sits unanswered, the longer it will take to trace and fix your bug. If you can no longer replicate the issue due to (e.g.) changing hardware or distribution, then tell us and we can close the bug report.

8. Do not “me too”. There is a vote link on the bug reports you can use to show you also experience the issue. Posting “me too” as a comment only clutters the tracker.

9. Use “LANG=C” for output. Prefixing a command with “LANG=C” will result in the output using the strings in the original code (English for most software). That way, we do not have to reverse-translate messages to understand the error.

Finally, remember that a bug does not exist until it is in the bug tracker. Reporting a bug on the mailing lists, forum, IRC, jabber, etc does not count. These are all fine for tracing the source of your bug before reporting it, but remember that bug trackers exist for a reason.

Edit (2001/05/12): Added #9.