Bug Reporting Guidelines
From Koha Wiki
Bug/Enhancement Reporting Guidelines
The Koha project makes use of a Bugzilla based bug tracking system. It is very important for Koha to have bugs listed on bugzilla. That is the list that the developers work from. If a bug is just mentioned in a posting to a mailling list, or just mentioned on IRC (chat) it can very easily slip through the cracks.
What is a bug?
A bug can be quickly identified as a problem with Koha. However, it is much more complicated than that. It can be a behavioural problem, or a component that does not work at all. It even applies to documentation that is incorrect. We also utilize Bugzilla for "future enhancements" or "feature requests".
Determine if you have a new bug
The first step to submitting a bug is to see if someone else has a similar problem to you.
- Search for an existing or similar bug
- If you find a similar bug, add yourself to the CC for the bug to be kept informed of progress. Leave a comment if you have something to add or wish to offer help in some way.
- Create a Bugzilla account (if needed)
- Log into Bugzilla.
- If you are unable to find an existing bug report, congratulations, you found a new bug! Click the new bug button to begin entering a new bug.
How to write good bug reports
Effective bug reports are the most likely to be fixed. These guidelines explain how to write such reports.
- Be precise
- Be clear - explain it so others can reproduce the bug. Screenshots and short narrated movies (Jing is a good free screen capture utility) are helpful as well.
- One bug per report
- No bug is too trivial to report - small bugs may hide big bugs
- Clearly separate fact from speculation
- Reproduce your bug using a recent build of the software, to see whether it has already been fixed.
- Search Bugzilla, to see whether your bug has already been reported.
Reporting a New Bug
If you have reproduced the bug in a recent build and no-one else appears to have reported it, then:
- Choose "Enter a new bug"
- Fill out the form. Here is some help understanding it:
Select the appropriate component. If you are unsure what area of Koha to report the error under, view the component list.
Select the version of Koha you are experiencing this issue under. (If you are unsure of the version of Koha you are using you can find the version in either the Intranet interface by selecting the "About" page, or else view the contents of your koha.conf file.) Additional Builds and Platforms: Whether or not the bug takes place on other platforms (or browsers, if applicable).
Doesn't Occur in 3.0.5
In most cases you can leave this as 'PC', as the OS is much more relevant.
Select your operating system. If you are unable to find your exact operating system, please pick the closest approximation and in the body of the ticket explain what operating system you are using.
The ticket priority helps us triage issues. Setting an appropriate level of priority helps us immensely.
|P1||This bug blocks development or testing work and should be fixed ASAP|
|P2||This bug blocks usability of a large portion of Koha, and really should be fixed before the next planned release|
|P3||Seriously broken, but not high impact. Should be fixed before next major release. Can include cosmetic bugs of particularly high visibility, and more minor bugs that are frequently reported|
|P4||Either a fairly straightforward workaround exists or the functionality is not very important and/or not frequently used|
|P5||Not that important, just fix when time permits|
This goes hand-in-hand with the priority line -- how bad do you think this bug is? This field describes the impact of a bug on a user. If a bug occurs with great frequency, it can be moved up in severity even if it doesn't meet the other criteria in that category.
|blocker||Needs to be fixed and an update released immediately. Example: bug results in data loss.|
|critical||Koha or component crashes and/or there is a potential loss of data|
|major||A major part of the component is nonfunctional.|
|normal||A minor part of the component is nonfunctional.|
|minor||The component mostly works, but causes some irritation to users.|
|trivial||The component works with 100% functionality, but has visible typos or other cosmetic problems|
|enhancement||an improvement of a feature already existing. This is different from "new feature" severity that is related to adding a feature that does not exist at all.|
|new feature||A feature request for functionality that does not currently exist. These can be useful as guides for future product improvements.|
You can use the URL field to reference external resources. Keep in mind that Bugzilla acts as a resource that will ideally last forever, while your external URL may not. Please include appropriate detail in your submission such that future reviewers may observe the entire issue report without having to potentially load an unsafe or nonexistant URL.
How would you describe the bug, in approximately 60 or fewer characters? A good summary should quickly and uniquely identify a bug report. It should explain the problem, not your suggested solution.
- Good: "Cancelling a File Copy dialog crashes File Manager"
- Bad: "Software crashes"
- Bad: "Browser should work with my web site"
The details of your problem report, including:
Overview: More detailed restatement of summary.
Steps to Reproduce: Minimized, easy-to-follow steps that will trigger the bug. Include any special setup steps.
1. View any web page. (I used the default sample page, resource:/res/samples/test0.html) 2. Drag-select the page. (Specifically, while holding down the mouse button, drag the mouse pointer downwards from any point in the browser's content region to the bottom of the browser's content region.)
Actual Results: What the application did after performing the above steps. Example:
The application closed, leaving the message "Program received signal SIGSEGV, Segmentation fault." in the log file.
Expected Results: What the application should have done, were the bug not present. Example:
The window should scroll downwards. Scrolled content should be selected. (Or, at least, the application should not crash.)
Additional Information: Any other useful information.
Double-check your report for errors and omissions, then press "Commit". Your bug report will now be in the Bugzilla database.
Bugzilla includes a general purpose Bug Writing Guidelines-page that you should review in its entirety before submitting a bug to Koha.
All Enhancements or sponsored items will be entered into http://bugs.koha-community.org which will allow users and developers access to what is currently in development as well as items that are being considered by libraries. Comments can be made on enhancements which will provide details for the development of the enhancement and to work out details with the libraries interested in the enhancement. This page of Enhancement Instructions outlines what needs to be put into the enhancement when entering into bugzilla.
Oh my! Thats too hard!
What is Bugzilla?
Bugzilla is a database of bugs and feature requests developed by the Mozilla project. It helps developers keep track of what's broken and who's fixing it. Users can help by making bug reports clear and specific. The better your bug report, the easier it is to identify the cause, and fix the bug.