Bug Reporting Guidelines

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 Bugzilla? Bugzilla is a database of bugs and feature requests developed by the Mozilla project. It helps developers to 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.

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".

How to write good bug reports

Effective bug reports are the most likely to be fixed. These guidelines explain how to write such reports.

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.

Principles

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

Preliminaries

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:

Component

Select the appropriate component. If you are unsure what area of Koha to report the error under, view the component list.

Version

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 the Staff interface on the "About Koha" page) You can also note other versions you have tested with in the bug report itself. If you have verified the problem in multiple versions, you can pick the newest version to report it against as bug fixes will be backported from the newest to the older versions.

Doesn't occur in 16.05
Verfified this also happens in 16.05, 16.11 and on current master

Platform

In most cases you can leave this as 'PC', as the OS is much more relevant.

OS

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.

Priority

The Koha project doesn't currently actively use the 'Priority' field in Bugzilla. You can safely leave this unset.

Severity

The severity field is quite important as this is what is used to triage the bug reports. 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.

Severity	Description
blocker	Needs to be fixed and an update released immediately. Bug is so bad that a release cannot go forth without fixing it Example: bug results in data loss.
critical	Koha or component crashes and/or there is a potential loss of data. The bug is very bad, but a release probably can go forth without fixing it, but probably shouldn't
major	A major part of the component is nonfunctional. The bug is seriously workflow impacting, but in a lesser used module or feature. A release is probably ok to go on without fixing it
normal	A minor part of the component is nonfunctional. This is most bugs - the bug is workflow impacting but isn't causing major trouble. Lots of UI/UX things go here. A release will very likely go on without a fix.
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.

URL

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.

Summary

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"

Also keep in mind that the summary is what people will see when bugs are listed in the search -- it's a good place to put keywords like which page the error occurs on, or specifics about where a problem occurs. The summary

Times are formatted incorrectly in slips ( AM PM ) due to double processing

accurately describes the problem, but someone looking for the bug later will be likely to search for date_due ISSUESLIP,

Time on <<issues.date_due>> incorrectly shows as 'AM' on ISSUESLIP, ISSUEQSLIP

Is easier to search for.

Description

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. Example:
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 "Submit Bug". 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.

Enhancement/Sponsorship Guidelines

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!

If you think that you may have discovered a bug but are not quite sure or comfortable posting it on Bugzilla post a message to one of the mailing lists or web forums and others can give advice.

Tester handbook

File and test bugs: Bug Reporting | Sandboxes
Other ways to help out: Chairing meetings
...

Developer handbook

Getting involved | Development workflow | Bug Reporting Guidelines | RFCs | Plugins | Plugin hooks
Version Control Using Git | git bz | Commit messages | Sign off on patches | QA Test Tools | How to QA | Debugging in VIM
Coding Guidelines | Koha Objects | Rest Api HowTo | Coding Guidelines - API | Unit Tests | Continuous Integration | Interface patterns | Database updates | Adding a syspref | Bootstrap and LESS
Debian Packages | Building Debian Packages | Easy Package Building | Commands
External: Dashboard | Bugzilla | Schema | perldoc | REST API | Jenkins