How to write a good bug report: step-by-step instructions

Isolate bug

The first step in in writing a bug report is to identify exactly what the problem is. Saying "something is wrong" is not helpful; saying exactly what is wrong, and how to reproduce it, is. If you can tell exactly what is wrong, and reliably reproduce an example of the problem, you've isolated a bug.

Check if you are using the latest version

Bug reports should be based on the the latest nightly build. If you are using a released version or an out-of-date build, please update to the latest revision and check to see whether or not the bug still exists.

Check if the bug is known

Please check whether the bug you are experiencing is already documented in the issue tracker. If it is already documented, you may click "subscribe" to follow any developments. If your bug is different than any others recorded in the issue tracker, "Create a new issue".

File each issue separately

If you have multiple issues, it is better to file them separately so they can be tracked more easily.

Create a new issue

Sign into MuseScore.org and go to the issue tracker (a link is found on the right side of every page). Click on "Create a new issue".

There are a number of initial questions that are used for filing a bug report - answers to these allow progress.

Project

The first question is which project your bug applies to. If in doubt, select "MuseScore", then "Next" to continue.

Component

Selecting the component is sometimes difficult. When in doubt, select "Code".

Category

A "bug report" is usually for when MuseScore does something contrary to what is expected: An example of a bug could be: open a specific file, but it instead crashes. Almost everything in the issue tracker consists of bug reports.

Tasks, feature requests and support requests are beyond the scope of this article, but generally it is recommended to discuss them first on the forum, instead of adding them directly to the issue tracker.

Priority

Every bug will have a different priority.

"Critical" is used if any of the following happens:

  • Data loss
  • Corruption
  • Score no longer opens
  • Inability to save work
  • Certain irreversible operations
  • Hangs and crashes

"Major":

  • Common feature incorrectly/not functioning
  • Otherwise critical issues, if they happen only in some very rare and esoteric corner cases

All other bugs are considered "normal" or "minor" priority. Bear in mind that while a bug that you are experiencing is important to you, developers have to balance it with all the other known bugs.

Status

The status of new bug reports should generally be marked as "Active".

Assign

If you intend to provide a fix, you can select your username. If otherwise, leave it 'unassigned'.

Title

The title should describe the problem as best as possible. Remember that the title is read more often than any other part of the bug report.

Poor title: Notes don't display correctly
This title is not specific enough for someone to look at it a month from now, and remember what the bug report is referring to.

Good title: Stems too short for 32nd and 64th notes
This title is an improvement over the previous title, because it specifies the type of notes that are affected and identifies the display problem.

After submitting the issue, it is possible to improve the title.

Description

Steps to reproduce bug

A bug report requires clear instructions, so that others can consistently reproduce it. Many bugs require some experimentation to find the exact steps that cause the problem you are trying to report. If you aren't able to discover these, try obtaining some help on the forums instead.

A good set of instructions includes a numbered list that details each button press, or menu selection. The following bug reports are good examples to mimic:

Note: the following bugs have all now been fixed

It can also be helpful to test your own instructions, as though someone else is trying them (as they will).

Expected behavior

Describe what should happen if the bug was fixed.

Actual behavior

In contrast to the expected behavior, describe what currently happens when the bug is present.

Version number

In MuseScore, go to About (listed in a top menu, depending on your operating system) to find out the version of MuseScore you are using. For example: "Version: 2.0.0, Revision 6e47f74, Nightly Build".

In the development builds the commit code can be obtained via 'About' and clicking the 'Copy to clipboard' button (results in something like 6e47f74, or in 'Help'>'Report a bug'.

Alternately, please state if you have compiled the source code and detail the versions of the third party tools.

Operating system

Name the operating system and version you are using, such as "Windows XP SP3", or "Mac OS X 10.7.5".

File attachments

If you can supplement your bug report with an MSCZ score, image, audio, or crash log that helps others reproduce the issue, attach these files.

Submit

"Save" to submit your bug report to the issue tracker.

Following up

Once a developer marks a bug as fixed, it is a good idea to ensure that it is completely fixed. To test, download the latest nightly build.