Reporting Issues

This article discusses the process of reporting bugs, feature requests, etc.

Tickets

Each bug, feature request, etc. should be submitted as a "ticket". A ticket provides a summary and a description of the issue, other information such as version, component and priority, the status of the issue (i.e. whether it is new, has been resolved, etc.), and comments about the issue. This allows the project team and other users to keep track of reported issues. You and other interested users can be notified of changes to the ticket; e.g. you will be notified if it is fixed. For more information about tickets, see TracTickets.

A ticket should only cover one single issue. Please do not file a single ticket covering multiple issues. Instead, file separate tickets for each issue.

Before Creating a Ticket

Before opening a new ticket, please first search existing tickets to determine whether the issue has already been reported.

To create and edit tickets, you need to register an account or log in if you already have an account.

Creating a New Ticket

To create a new ticket:

  1. Select the link to create a new ticket on the Development page.
  2. Fill in the fields in the new ticket form. The main fields are described below.
  3. You may also attach files to the ticket if appropriate; e.g. log files or patches.
  4. Press the "Create ticket" button.

Ticket Fields

These are the basic fields:

  • Summary: A short sentence or phrase briefly summarising the issue. This should identify the issue as clearly as possible.
  • Description: A thorough description of the issue. If you are reporting a bug, you should describe how often the problem occurs, detailed steps to reproduce the problem, the results you expected and the actual results. Include any additional information that might be relevant.
  • Type: The type of the issue; i.e. defect (bug), enhancement or task.
  • Component: The component/area of NVDA to which the issue is related. See TicketComponents for explanations of the components.
  • Version: The version of NVDA in which the issue occurred or to which it is relevant. Select "development" if you are running a development snapshot. Please note that issues relating to old releases will not be considered, so please do not open tickets for them.
  • Operating system: The operating system on which the issue occurs. Only specify this if the issue is specific to that operating system.

There are also some other advanced fields which can be seen by all users but can only be changed by developers:

  • Priority: The importance of the issue.
  • Milestone: The version of NVDA in which the issue should be resolved.
  • Keywords: A space separated list of keywords which provide other meta information about the ticket. See TicketKeywords for a list of keywords.
  • Blocked by: A comma separated list of ticket numbers which block this ticket; i.e. tickets that this ticket depends on.
  • Blocking: A comma separated list of ticket numbers which this ticket is blocking; i.e. tickets that depend on this ticket.

Editing Tickets

You can edit information about, comment on or attach a file to a ticket. Simply view the ticket you wish to edit and change the appropriate fields on the form.

Providing Log Files

When reporting problems, it is always useful to provide an NVDA log file. This file shows what NVDA was doing when the error occured. Many times a particular error is not reproduceable on other systems, so the log file can act as a further description or recording of the problem as it happened.

A log file should be attached to a ticket at the same time or after it is created. It is important not to simply paste fragments or entire log files in to the comment or description of a ticket, as this clutters the ticket and may mangle certain information needed from the log.

To retrieve a log file to be attached to a ticket, after the error occurs and before closing NVDA, do the following:

  1. Open the log viewer found under Tools in the NVDA menu.
  2. In the log viewer, choose Save As from the Log menu, and save the file to a place of your choice.
  3. Finally, this file you have saved can be attached to the ticket on the NVDA website.

If however you have already closed NVDA, or NVDA crashed, you can always find the log file for the last time NVDA was running. This file can be found in the temp directory %temp% and is called nvda.log. For those running from source, nvda.log is in the source directory. This file can be attached to the ticket.

By default, NVDA's log level is set to Info. This means that only informational messages, warning messages and major error messages are logged. This level of logging may be useful for crashes of NVDA or when nothing better is available. However, if you wish to provide much more detail, it is very useful if NVDA's log level could be set to debug (In General Settings under Preferences in the NVDA menu) before the error occurs. Setting the log level to debug tells NVDA to also log information such as what keys were pressed, what was spoken and messages regarding particular code internal to NVDA. Although this detail will help a great deal in solving the issue, please be aware that because key presses and spoken messages are logged, the log may contain personal information.