= RTEMS Bug Reporting =

[[TOC(Developer/Bug_Reporting, depth=2)]]

Our preferred way of receiving bug reports is via the [http://devel.rtems.org RTEMS Trac] ticket system. If you have patches not specifically related to bugs or existing tickets, we prefer to use the [wiki:TBR/Website/RTEMSMailingLists Developer's Mailing List].

In general, if you have a bug to submit follow the instructions:
 
1. Sign in to the RTEMS Trac website using the [https://devel.rtems.org/login Trac Login].
1. Click in [https://devel.rtems.org/query View Tickets] (upper right corner of the screen).
1. Search for a similar ticket about the bug (to avoid duplicates).
1. If you haven't found a similar ticket, create a [https://devel.rtems.org/newticket New Ticket] and:
  a. Add a useful single line summary.
  a. Set the `Type` field to `defect` for a bug. Note `infra` is used to report issues with the RTEMS servers at OSUOSL.
  a. Set the `Version` field. If it is with the current git master branch use the next version
  a. Set the `Component` field and leave as `General` if you are not sure.
  a. Describe the bug or issue in the `Description` field with any details useful to the RTEMS maintainers such as host machine, build of tools, output traces, plus if you have any local modification and detailed instructions in order to reproduce the bug. The `WikiFormatting` is useful in formatting the information you provide and it does help the readability of the information you provide.
  a. Click `Create Ticket` when you are happy you have all the details you can provide.

The [wiki:TracWorkflow Trac Ticket Workflow] details the workflow for RTEMS Tickets.

= Managing Bugs =

This section contains information mostly intended for RTEMS contributors.  But if you submit a bug report, it is very important for you to submit a reproducible test case.  These submitted test cases end up being added to the test suite to prevent future regressions.

If you find a bug, but you are not fixing it (yet):
* Create a (minimal) test-case.
* Add the test-case to our test-suite, documenting it as a current failure unless the bug is a regression.
* Add a bug report referencing the test-case to Trac.

If you want to provide additional information in the bug tracking system about a reported bug:

* If the bug has been tracked down to a specific area or routine in RTEMS, please provide information about its location.
* Minimize the test case.
* Try the test case with earlier and later versions of RTEMS to determine which versions it affects and whether it is a regression. If it is a regression, identify the patch that introduced it.

If you fix a bug for which there is already a Trac ticket:

* Remove the failure notation on the test-case.
* Attach your fix and test case to the Trac ticket.
* Close the ticket by adding `fixes #<ticket numer>` to the commit message.

If you find a bug, and you are fixing it right then:

* Create a (minimal) test-case.
* Add the test-case to our test-suite, documenting it as known to work.
* Check in your fixes.

The state of a ticket is:

   '''open''':: The ticket has been filed and the responsible person(s) notified.
  '''accepted''':: The assigned maintainer has verified that this is indeed a bug in RTEMS. Every once in a while, old reports will need to be rechecked, to find out whether the bug still exists. At that time, an indication should be left in the report who tested the bug and when.

The `resolve` action has the following:

  '''fixed''':: The bug has been fixed. 
  '''invalid''':: The bug report is not valid and nothing further will be done.
  '''wontfix''':: The bug will not be fixed.
  '''duplicate'''::The ticket is a duplicate of any other ticket and that ticket should be referenced in future.
  '''worksforme''':: The bug could not be repeated and there is not more the maintainer can do.

If a bug has been closed and you think there has been a mistake please reopen the ticket and add suitable comments to explain the reason for reopening the ticket.

The high priority is reserved to maintainers in RTEMS, indicating that a certain problem must be solved before the next version of RTEMS is released.

Tickets can be automatically updated using a git commit message. If the commit contains `fixes #12345` the ticket ''12345'' will be closed and the commit message used a comment in the ticket. The valid keywords are:

  '''Close a ticket''':: `close` `closed` `closes` `fix` `fixed` `fixes` `Close` `Closes` `Closed` `Fix` `Fixed` `Fixes`

  '''Update a ticket''':: `addresses` `references` `refs` `see` `address` `update` `updates` `Refs` `See` `Address` `Update` `Updates`