Bug tracking is an important part of a continuous quality control process. Unlike most proprietary software programs, Moodle bug reporting and bug tracking information is open to everyone. Moodle's bug tracking system is called Tracker. Tracker is a slightly customised version of Atlassian's product Jira.
"Bugs" not only include software problems with current versions of Moodle, but requests for new features, imporvements, even constructive criticism of existing features is welcome.
The beauty of open source is that anyone can participate and help to create a better product for all of us to enjoy. In this project, your input is very welcome!
Logging in to Tracker
- If you're a new Tracker user, create a user account here. It is strongly suggested your Tracker username is the same name you use at Moodle.org.
- If you've forgotten your password, go here and select 'forgot password' which is just under the 'log in' button. Follow the prompts.
How to report a bug, improvement, or new feature request
NB See the section 'Tracker fields' below for a full description of every field.
- Login to Tracker
- Select "Create New Issue" from the menu under the Moodle Tracker logo
- From the dropdown menu select the "Issue type": Bug, New Feature, Task or Improvement
- You will see a series of dropdown and free text fields. Complete as many as you can. Some fields are required while others are optional.
- Press the 'Create' button at the bottom of the page to create the bug.
NB A short explanation appears under each field in Jira.
Project - Required field. Tracker is made of of multiple projects. At present there are 2: 'moodle' and 'moodle.org sites'. Specify 'moodle' for issues/bugs related to moodle software; specify 'moodle.org sites' for issues/bugs related to tracker.moodle.org, docs.moodle.org, demo.moodle.org, download.moodle.org, or moodle.org.
Issue Type - Required field. Bugs are classified as 1 of the following:
- Bug - A problem which impairs or prevents Moodle from functioning correctly.
- Improvement - An enhancement to an existing Moodle feature.
- New Feature - A new Moodle feature which has yet to be developed.
- Task - A task that needs to be completed. Tasks usually refer to work that must be done outside the product.
- Sub-Task - Issues are sometimes broken into multiple sub-tasks.
Summary - Required field. A brief, concise description of the problem.
Security Level - Optional field. Specify if this bug or change has security implications for Moodle.
Priority - Bugs are prioritised using one of the following:
- Blocker - Blocks development and/or testing work, production could not run.
- Critical - Crashes, loss of data, severe memory leak.
- Major - Major loss of function.
- Minor - Minor loss of function, or other problem where easy workaround is available.
- Trivial - Cosmetic problem like misspelled words or misaligned text.
Component/s - Required field. Select the area in Moodle which is affected by this bug. Select 'Unknown' if you are unsure.
Affects Version/s - This is the Moodle version in which the bug has been found. It is normally entered by the person logging the bug, and typically only 1 version is specified. Enter a version in this field when you are logging an 'improvement', 'task', or 'new feature' as this will help assess the state of the product when the request was made.
Assigned To - This is the person who will fix (code) the problem. This field is completed by developers or Component Leads.
Reporter - The person who logs the bug. This field is automatically filled by Tracker.
Environment - Specify the operating system, software platform and/or hardware specifications if applicable to this bug.
Description - A full and complete yet concise description of the problem or improvement.
Database - Optional field. If applicable to the bug, identify the database type.
URL - Optional field. If possible, provide a URL address that demonstrates an example of this bug.
QA Assignee - Used to designate the person who will test this bug.
Fixed Version/s - This is the Moodle version the bug was or will be fixed in. This field is normally completed by the developer when the bug has been resolved or by lead developers allocating bugs for a specific release. Normally only one version is specified in this field. It symbolises the first version of Moodle where the change will be seen.
Attachment - Optional. Attach a file that will help developers and testers better understand the bug. Maximum attachement size is 512Kb.
Comment - The comment field is a detailed register of all changes that relate to this bug.
Resolution - This field is only displayed when resolving or closing a bug. Specify a code that best describes how this bug was resolved.
- Fixed - Bug has been fixed; a code change will be checked into CVS. Use this resolution code only when actual changes were made to Moodle code.
- Won't Fix - The problem described is an issue which will never be fixed.
- Not a bug - This issue is not a bug; was logged in error. Use this code if the bug was fixed by another bug report or in some earlier Moodle version.
- Duplicate - The problem is a duplicate of an existing issue.
- Incomplete - More information is needed to understand this bug.
- Can't Reproduce - All attempts at reproducing this issue failed, or not enough information was available to reproduce the issue. Reading the code produces no clues as to why this behavior would occur. If more information appears later, please reopen the issue.
- Deferred - The resolution to this bug will be deferred to a later release.
Resolving bugs in Tracker
NB Only Moodle core developers and testers are permitted to change the status of bugs in Tracker to "resolved" or "closed".
- Bugs are assigned by developers or Component Leads.
- Developers modify or add code and check into CVS.
- Appropriate comments are added in Tracker. The bug's status is changed to Resolved by using the "Resolve Issue" button.
- You must indicate the version of Moodle in which the change has been made. Do this by selecting the appropriate Moodle version in Fix Version/s.
- The only exception to not moving a bug to Resolved is if a developer believes there is no value in testing the issue, in which case the bug status can be changed to Closed.
All users are encouraged to be active participants when it comes to testing Moodle. Anyone with a Tracker user account can log, view, comment on, vote, and watch bugs. If you find bugs or problems, have ideas for improvements, or want additional functionality added to Moodle, please log a bug in Tracker.
We've formalised a group of testers in Tracker who are responsible of verifying the accuracy of changes made by developers. These testers have responsibilities and authority in Tracker beyond that of standard users. Testers normally have a good understanding of Moodle, and are active in the Moodle community. If you are interested in becoming a member of the Moodle Testing team make yourself known by logging a request through Tracker. We'd love to have you join the team. Log your request at the Moodle.org Sites Tracker project.
Testing a bug in Tracker: NB This process members of the moodle-testers group should follow to move bugs from 'resolved' to 'closed'.
- Testers test bugs with Status=Resolved. Global filters have been created based on upcoming releases (eg 1.7 Resolved) to make identification simple.
- Use the QA Assignee field to identify yourself as the tester of a particular bug. Obviously you should have the skills and knowledge to sufficiently test the issue. Experience is important, but don't forget there are others in the community that may be able to help you.
- It's a good idea to add your name to the watch list for all bugs you test. (see "Tracker watch list", below.)
- If the bug passes testing, close the bug using the "Close Issue" button. You must add appropriate comments describing your testing methods, any issues that were found, etc.
- If the bug fails testing or if you feel the fix is incomplete, reopen the bug using the "Reopen Issue" button. Ensure the bug is assigned to the correct developer. Work with the developer to find a mutually agreeable resolution to the bug.
- A release will be deemed ready when all bugs fixed for a particular version have been closed.
More about Tracker functionality
- You will receive an email when you log a new bug or make updates to bugs you've reported. You'll also receive notification when updates are made to bugs you're watching. Read on for more information on watching a bug.
- You can monitor, or "watch" bugs reported by others. To do this, open the bug, then select "Watch it" from the left hand navigation panel. To add others to the watchlist for your bug, open the bug, select the option "Watching" from the left hand navigation panel. These people will receive email notification when updates are made to this bug.
- Tracker provides a facility to Link bugs. Any user logged onto Tracker may link issues. Multiple link types are defined in the system; you will be required to select one when linking bugs. The following link types are available:
- duplicates - duplicates are inevitable in a project the size of Moodle. They occur when a logger is unaware of an existing bug that describes the same problem. Use duplicates to link to the first or most comprehensively described instance of the problem. All duplicates should be linked together.
- blockers - use this to identify bugs that block others from being fixed.
- cloners - in some instances a duplicate bug is intentionally created in order to track the fix in another branch of the code - this almost never is used in the Moodle project.
- dependency - often a fix is dependent on another bug being resolved first, on in a specific order.
- relates - used to identify a bug that is somehow related to another bug.
- Links are bi-directional meaning that there's a concept of 'inward' and 'outward' - it affects how linked bugs are displayed. This is why you'll see "blocks/is blocked by" or "duplicates/is duplicated by" in the drop down list of the Link Issue dialog. Don't become too concerned about using the "correct" link type - all link types work similarly.
- Don't be afraid to link bugs. It's very helpful to developers and testers to get a complete picture of a problem.
- Vote for bugs you want to see addressed in Moodle. Any user can vote. To vote for a specific bug, browse to the bug, then select "Vote for it" from the left-hand navigation panel. Developers may consider the number of votes a bug has when weighing the merits of two or more bugs.
- The Tracker Dashboard is flexible and customisable depending on your area of interest. For instructions on configuring the Tracker dashboard click here.
- The Tracker Issue Navigator is used to find and filter bugs. For instructions on configuring the Issue Navigator click here.
- Tracker's Quick Search function is explained here
Tracker groups and permissions
Standard Users [groupname=jira-user] - This is the default group. New user accounts are placed in this group at the time of creation, and users must be a member of this group in order to log into Tracker. Members of this group can browse bugs, create new bugs, comment on bugs, create attachments, create sub-tasks, create filters, watch bugs, and vote for bugs. Members of this group can also resolve bugs, which is primarily a way of closing bugs that are no longer relevant (eg duplicates, or logged in error). Standard Users can configure their Tracker workspace by using the "Configure your Issue Navigator" button. This feature allows users to view watch and voting lists and to manage preferences, profile, and password.
Developers [groupname=jira-developer] - Developers can do everything Standard Users can do. In addition they can clone bugs, close bugs, edit bugs, link bugs, and assign bugs. Members of this group can also use the Bulk Edit function which allows bulk updated to multiple bugs.
Testers [groupname=moodle-testers] - Testers can do everything a Developer can do.
NB You can browse a project while not logged in to Tracker, however you will be unable change/edit/comment on bugs.
General reporting guidelines
Good bug reports address these elements (in the field Description):
- Steps to reproduce. That is, a detailed sequence of steps a developer can follow to see the problem. It is very hard to fix a bug that is not reproducible. If possible, provide a URL so we can see the problem with one click.
- What I expected to happen. Again, provide as much detail as possible. Your expectation might mean that our instructions need to be improved or our interface should be changed.
- What actually happened (with detail).
- If you have an error message, or information in your PHP or web server logs, copy and paste it into the bug report. If you can, turn on "debug" in your Admin configuration page and reproduce the problem to get the best possible error message.
- Screen shots are very helpful for some bugs, but please write a textual description of the problem too.
- Make sure we know everything we need to know about your setup including operating system, database, etc. If you run out of room in the environment section, add more detail in the description. The full set of information that might be relevant is:
- Server operating system type and version number
- Web server type and version number
- PHP version number (and whether you are using an accelerator)
- Database type and version number
- Moodle version (there is a dropdown menu on the top of the form, if that does not have what you want, add it in the description)
- Client-side operating system type and version number
- Web browser type and version number
You don't need to give all those details all the time. For example, for a layout rendering problem, you need to give only the client-side OS and browser info, and if it is a server-side problem you only need to describe the setup there. Use your judgment. Here are some examples:
- I see this bug with the latest Moodle HEAD running on PHP5.1.2/Apache 2.2.3 on Linux. My database is Postgres 8.1.
- This rendering problem happens using Internet Explorer 6.0 on Windows XP.
In summary stick with facts and present enough facts so someone else can duplicate the problem.
"What’s the hardest thing about a bug report?" Most of the time fixing the problem is the easy part, the hard part is reproducing the bug. The developer needs to see how it is broke to be able to fix it. If they can't reproduce the error you can be sure they won't be able to fix it!
Good bug reports contain as much detail as possible and are specific. Don't generalise or leap to conclusions.
For example, a bug report that only says "The RSS feed doesn’t support UTF-8" is not helpful. The developer knows that UTF-8 and RSS feeds are compatible. The developer has no idea of what the person sees and why they reported this bug. In this case more time and effort needs to be expended to determine the problem.
Consider a bug report which says that the descriptions for the specific RSS feed XYZ@abc shows unrecognisable characters rather than expected characters.