Changeset e21c413 in rtems-docs

Aug 6, 2019, 9:58:05 AM (2 weeks ago)
Sebastian Huber <sebastian.huber@…>
Sebastian Huber <sebastian.huber@…> (08/06/19 09:58:05)
Sebastian Huber <sebastian.huber@…> (08/08/19 06:04:57)

user: Improve bug report section

The new content is based on the wiki page:

The goal is to remove the wiki page and direct the "New ticket" page to
this user manual section. Some content of the wiki page should move to
the "Contributing" sections since it is not directly related to bug
reporting, e.g. managing existing bugs.

4 edited


  • user/index.rst

    r7c89bd6 re21c413  
    1717    | |copy| 2016, 2019 embedded brains GmbH
    1818    | |copy| 2016, 2019 Sebastian Huber
    19     | |copy| 2012, 2019 Chris  Johns
     19    | |copy| 2012, 2019 Chris Johns
     20    | |copy| 2012 Gedare Bloom
    2021    | |copy| 1988, 2018 On-Line Applications Research Corporation (OAR)
  • user/support/bugs.rst

    r7c89bd6 re21c413  
    33.. Copyright (C) 2019 embedded brains GmbH
    44.. Copyright (C) 2019 Sebastian Huber
    5 .. Copyright (C) 2016 Chris Johns <>
     5.. Copyright (C) 2015 Chris Johns <>
     6.. Copyright (C) 2012 Gedare Bloom
    78.. index:: bugs
    89.. index:: reporting bugs
    10 Bugs
    11 ****
     11Report Bugs
    13 The bug tracker can be found at the :r:url:`bugs`.
     14The RTEMS Project uses a ticket system to deal with bugs, organize enhancement
     15requests, and manage small tasks and projects.  You can `submit a bug report
     16<>`_ to the RTEMS Project ticket system.
     17Before you do this, please read the following information.  Good bug reports
     18are more likely to get addressed quickly.  If you have patches not specifically
     19related to bugs or existing tickets, please have a look at the
     20:ref:`Contributing` guidelines.
    15 See the `Submission Guidelines <>`_ for
    16 details on submitting a ticket.
     22Search for Existing Bugs
    18 Be sure to do a cursory search for any tickets that may be relevant to your
    19 problem.
     25You can `search for existing bugs <>`_ in the
     26RTEMS Project ticket system.  Please try to avoid duplicate bug reports and
     27search for an existing bug before you report a new bug.  If you are unsure,
     28please ask on the :r:list:`users` and we will help you sort it out.
    21 If you are unsure about your issue status submit a ticket and we will help you
    22 sort it out.
     30Not RTEMS Bugs
     33Some issues appear to be an RTEMS bug to you, but are actually the intended
     34behaviour or in the scope of other projects.
     36* Bugs in the assembler, the linker, or the C library (Newlib) are not RTEMS
     37  bugs.  These are separate projects, with separate mailing lists and different
     38  bug reporting procedures. The RTEMS Project is happy to work with you and
     39  those projects to resolve the problem but we must work with those projects.
     40  Bugs in those products must be addressed in the corresponding project.  Report
     41  `assembler, linker, and GDB bugs to <>`_,
     42  `compiler bugs to GCC <>`_, and
     43  `Newlib bugs to the Newlib mailing list <>`_.
     44  If the bug was fixed, then you can update the :ref:`RSB` to pick up the fix.
     46* Questions about the correctness or the expected behaviour of programming
     47  language constructs or calls to library routines that are not part of RTEMS
     48  belong somewhere else.
     50* The POSIX standard does *not* specify the default set of thread attributes.
     51  Thus, when passing a NULL for attributes to pthread_create(), the application
     52  is not guaranteed any particular thread behaviour.
     54* The defaults for all
     55  `RTEMS Application Configuration <>`_
     56  parameters are intentionally small. Thus, it is common for RTEMS tasking and
     57  file related calls to return errors indicating out of resources until the
     58  configuration parameters are properly tuned for the application. For example,
     59  there are only three file descriptors available by default: stdin, stdout, and
     60  stderr. Any attempt to open a socket or file will fail unless more file
     61  descriptors are configured.
     63* When first developing a BSP, many users encounter an unexpected interrupt or
     64  exception immediately upon completion of RTEMS initialization. This occurs
     65  because interrupts are disabled during RTEMS initialization and are
     66  automatically initialized as part of switching to the first task. The
     67  interrupted user code will be in either _CPU_Context_switch() or
     68  _Thread_Handler().  This indicates that an interrupt source has not been
     69  properly initialized or masked.
     71* Some users encounter a random reset during BSP initialization. This usually
     72  indicates that the board has a watchdog timer that is not being properly
     73  serviced during the BSP initialization.
     75* Bugs in releases or snapshots of RTEMS not issued by the RTEMS Project.
     76  Report them to whoever provided you with the release.
     78Good Bug Reports
     81Please open the page to `submit a bug <>`_ to
     82the RTEMS Project ticket system and follow the guidelines below to write a good
     83bug report.
     85* Provide a useful single line summary.
     87* Use `WikiFormatting <>`_ to
     88  structure the information you provide.  It does help the readability of the
     89  information you provide.
     91* Add a description of the expected behaviour.  The expected behaviour may be
     92  obvious to you, but maybe not to someone else reading the bug report.
     94* Add a description of the actual undesired behaviour.
     96* Name the :ref:`target hardware <Hardware>` (processor architecture, chip family
     97  or model, and :ref:`BSP <BSPs>`) in the description.
     99* Add the toolchain version used (GCC, Binutils, Newlib) to the description.
     100  Custom toolchain builds are discouraged.  To avoid problems caused by custom
     101  builds of the toolchain, please build your toolchain with the :ref:`RSB`.  If
     102  you use a custom build of the toolchain, then try to reproduce the bug first
     103  using a toolchain built by the RSB.
     105* Provide the configuration options used to build the RTEMS BSP in the
     106  description.  This helps to reproduce the issue.
     108* Make the bug reproducible by others.  Write a self-contained piece of source
     109  code which can be compiled and reproduces the bug.  Avoid adding assembly
     110  files (\*.s) produced by the compiler, or any binary files, such as object
     111  files, executables, core files, or precompiled header files.  If it is
     112  difficult or time consuming to reproduce the bug, then it may not get the
     113  attention it deserves from others.  Developing and debugging real-time
     114  embedded systems can be difficult.  Exercise caution in reporting an error
     115  that occurs only some of the times a certain program is executed, such that
     116  retrying a sufficient number of times results in a successful compilation;
     117  this is often a symptom of a hardware problem or application issue, not of a
     118  RTEMS bug (sorry). We do recognise that sometimes a timing bug will exist in
     119  RTEMS, but we want you to exercise due diligence before pointing fingers.
     121* Only when your bug report requires multiple source files to be reproduced
     122  should you attach an archive. Otherwise, the uploaded individual source file
     123  or diff should contain the minimal source code needed to reproduce the bug.
     124  In any case, make sure the above are included in the body of your bug report
     125  as plain text, even if needlessly duplicated as part of an archive.
     127* Please try to reproduce the bug on the current Git master.  If it is not
     128  reproducible on the Git master, you should figure out if the bug was already
     129  fixed.  You can search the existing bugs once again, ask on the
     130  :r:list:`users`, or do a Git bisect to find a commit which fixed the bug.
     132* Include only information relevant to the bug.
     134* Write separate bug reports for different bugs.
     136* Select a *Type* for the ticket.  Use ``defect`` for a bug.  Note ``infra`` is
     137  used to report issues with the RTEMS servers at OSUOSL.
     139* Select a *Version* for the ticket.  This should be the first RTEMS version
     140  which is affected by this bug.  If this is the current Git master branch use
     141  the version of the next release.  Please provide the exact version of RTEMS
     142  in the description.  If you use an RTEMS release, then the release number.
     143  If you use a Git clone, then the commit hash.  The commit hash should be
     144  present in an RTEMS Project repository.  Commit hashes of private branches
     145  are not interesting.
     147* Select a *Component* for the ticket.  Use ``unspecified`` if you are unsure.
     149* Select a *Severity* for the ticket.
     151* The fields *Milestone* and *Priority* will be most likely set by an RTEMS
     152  maintainer.
     154* You can relate your new bug to existing bugs through the *Blocked by* and
     155  *Blocking* fields.
     157When you have checked that your report meets the criteria for a good bug
     158report, please click on the ``Create ticket`` button to submit it to the RTEMS
     159Project ticket system.
     161If you fail to supply enough information for a bug report to be reproduced,
     162someone will probably ask you to post additional information. In this case,
     163please post the additional information and not just to the person who requested
     164it, unless explicitly told so.
     166Nobody Fixes my Bug
     169Sometimes, you may notice that after some time your bug report gets no
     170attention and the bug is not magically fixed.  This may have several reasons
     172* the bug report is incomplete or confusing,
     174* the target hardware is not available to others,
     176* the bug is not reproducible on the Git master,
     178* the bug is not reproducible at all,
     180* the RTEMS version is quite old and no longer used by RTEMS maintainers,
     182* fixing the bug has a low priority for others.
     184Please note that you do not have a service contract with the RTEMS Project.
     185The RTEMS Project is run by volunteers and persons who take care about how
     186RTEMS performs in their application domain.  If your bug does not affect the
     187interest of someone else, then you should try to fix the bug on your own, see
     188the :ref:`Contributing` guidelines.  To change the priorities of others with
     189respect to your bug, you may refer to the :ref:`SupportCommercial`.
  • user/support/contrib.rst

    r7c89bd6 re21c413  
    77.. index:: community; developers
     9.. _Contributing:
  • user/support/support-commercial.rst

    r7c89bd6 re21c413  
    55.. index:: support; commercial
     7.. _SupportCommercial:
    79Commercial Support Services
Note: See TracChangeset for help on using the changeset viewer.