[PATCH] user: Improve bug report section
Gedare Bloom
gedare at rtems.org
Tue Aug 6 18:29:52 UTC 2019
On Tue, Aug 6, 2019 at 4:01 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> The new content is based on the wiki page:
>
> https://devel.rtems.org/wiki/Developer/Bug_Reporting
>
> 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.
> ---
> user/index.rst | 3 +-
> user/support/bugs.rst | 187 ++++++++++++++++++++++++++++++++++--
> user/support/contrib.rst | 2 +
> user/support/support-commercial.rst | 2 +
> 4 files changed, 183 insertions(+), 11 deletions(-)
>
> diff --git a/user/index.rst b/user/index.rst
> index 6491c6c..eff85f3 100644
> --- a/user/index.rst
> +++ b/user/index.rst
> @@ -16,7 +16,8 @@ RTEMS User Manual (|version|).
> | |copy| 2017 Tanu Hari Dixit
> | |copy| 2016, 2019 embedded brains GmbH
> | |copy| 2016, 2019 Sebastian Huber
> - | |copy| 2012, 2019 Chris Johns
> + | |copy| 2012, 2019 Chris Johns
> + | |copy| 2012 Gedare Bloom
> | |copy| 1988, 2018 On-Line Applications Research Corporation (OAR)
>
> .. include:: ../common/license.rst
> diff --git a/user/support/bugs.rst b/user/support/bugs.rst
> index 1ad1b5f..16d58cc 100644
> --- a/user/support/bugs.rst
> +++ b/user/support/bugs.rst
> @@ -2,21 +2,188 @@
>
> .. Copyright (C) 2019 embedded brains GmbH
> .. Copyright (C) 2019 Sebastian Huber
> -.. Copyright (C) 2016 Chris Johns <chrisj at rtems.org>
> +.. Copyright (C) 2015 Chris Johns <chrisj at rtems.org>
> +.. Copyright (C) 2012 Gedare Bloom
>
> .. index:: bugs
> .. index:: reporting bugs
>
> -Bugs
> -****
> +Report Bugs
> +***********
>
> -The bug tracker can be found at the :r:url:`bugs`.
> +The RTEMS Project uses a ticket system to deal with bugs, organize enhancement
> +requests, and manage small tasks and projects. You can `submit a bug report
> +<https://devel.rtems.org/newticket>`_ to the RTEMS Project ticket system.
> +Before you do this, please read the following information. Good bug reports
> +are more likely to get addressed quickly. If you have patches not specifically
> +related to bugs or existing tickets, please have a look at the
> +:ref:`Contributing` guidelines.
>
> -See the `Submission Guidelines <http://devel.rtems.org/wiki/NewTicket/>`_ for
> -details on submitting a ticket.
> +Search for Existing Bugs
> +========================
>
> -Be sure to do a cursory search for any tickets that may be relevant to your
> -problem.
> +You can `search for existing bugs <https://devel.rtems.org/query>`_ in the
> +RTEMS Project ticket system. Please try to avoid duplicate bug reports and
> +search for an existing bug before you report a new bug. If you are unsure,
> +please ask on the :r:list:`users` and we will help you sort it out.
>
> -If you are unsure about your issue status submit a ticket and we will help you
> -sort it out.
> +No RTEMS Bugs
No -> Not
> +=============
> +
> +Some issues appear to be an RTEMS bug to you, but are actually the intended
> +behaviour or in the scope of other projects.
> +
> +* Bugs in the assembler, the linker, or the C library (Newlib) are no RTEMS
no -> not
> + bugs. These are separate projects, with separate mailing lists and different
> + bug reporting procedures. The RTEMS Project is happy to work with you and
> + those projects to resolve the problem but we must work with those projects.
> + Bugs in those products must be addressed in the corresponding project. Report
> + `assembler, linker, and GDB bugs to sourceware.org <https://sourceware.org/bugzilla/enter_bug.cgi>`_,
> + `compiler bugs to GCC <https://gcc.gnu.org/bugzilla/enter_bug.cgi>`_, and
> + `Newlib bugs to the mailing list <https://sourceware.org/newlib/>`_.
"the newlib mailing list"
> + If the bug was fixed, then you can update the :ref:`RSB` to pick up the fix.
> +
> +* Questions about the correctness or the expected behaviour of programming
> + language constructs or calls to library routines that are not part of RTEMS
> + belong to somewhere else.
delete 'to'. Add a link to StackExchange? :-)
> +
> +* The POSIX standard does *not* specify the default set of thread attributes.
> + Thus, when passing a NULL for attributes to pthread_create(), the application
> + is not guaranteed any particular thread behaviour.
> +
> +* The defaults for all
> + `RTEMS Application Configuration <https://docs.rtems.org/branches/master/c-user/configuring_a_system.html>`_
> + parameters are intentionally small. Thus, it is common for RTEMS tasking and
> + file related calls to return errors indicating out of resources until the
> + configuration parameters are properly tuned for the application. For example,
> + there are only three file descriptors available by default: stdin, stdout, and
> + stderr. Any attempt to open a socket or file will fail unless more file
> + descriptors are configured.
> +
> +* When first developing a BSP, many users encounter an unexpected interrupt or
> + exception immediately upon completion of RTEMS initialization. This occurs
> + because interrupts are disabled during RTEMS initialization and are
> + automatically initialized as part of switching to the first task. The
> + interrupted user code will be in either _CPU_Context_switch() or
> + _Thread_Handler(). This indicates that an interrupt source has not been
> + properly initialized or masked.
> +
> +* Some users encounter a random reset during BSP initialization. This usually
> + indicates that the board has a watchdog timer that is not being properly
> + serviced during the BSP initialization.
> +
> +* Bugs in releases or snapshots of RTEMS not issued by the RTEMS Project.
> + Report them to whoever provided you with the release.
> +
> +Good Bug Reports
> +================
> +
> +Please open the page to `submit a bug <https://devel.rtems.org/newticket>`_ to
> +the RTEMS Project ticket system and follow the guidelines below to write a good
> +bug report.
> +
> +* Provide a useful single line summary.
> +
> +* Use `WikiFormatting <https://devel.rtems.org/wiki/WikiFormatting>`_ to
> + structure the information you provide. It does help the readability of the
> + information you provide.
> +
> +* Add a description of the expected behaviour. The expected behaviour may be
> + obvious to you, but maybe not to someone else reading the bug report.
> +
> +* Add a description of the actual undesired behaviour.
> +
> +* Name the :ref:`target hardware <Hardware>` (processor architecture, chip family
> + or model, and :ref:`BSP <BSPs>`) in the description.
> +
> +* Add the toolchain version used (GCC, Binutils, Newlib) to the description.
> + Custom toolchain builds are discouraged. To avoid problems caused by custom
> + builds of the toolchain, please build your toolchain with the :ref:`RSB`. If
> + you use a custom build of the toolchain, then try to reproduce the bug first
> + using a toolchain built by the RSB.
> +
> +* Provide the configuration options used to build the RTEMS BSP in the
> + description. This helps to reproduce the issue.
> +
> +* Make the bug reproducible by others. Write a self-contained piece of source
> + code which can be compiled and reproduces the bug. Avoid adding assembly
> + files (\*.s) produced by the compiler, or any binary files, such as object
> + files, executables, core files, or precompiled header files. If it is
> + difficult or time consuming to reproduce the bug, then it may not get the
> + attention it deserves from others. Developing and debugging real-time
> + embedded systems can be difficult. Exercise caution in reporting an error
> + that occurs only some of the times a certain program is executed, such that
> + retrying a sufficient number of times results in a successful compilation;
> + this is often a symptom of a hardware problem or application issue, not of a
> + RTEMS bug (sorry). We do recognise that sometimes a timing bug will exist in
> + RTEMS, but we want you to exercise due diligence before pointing fingers.
> +
> +* Only when your bug report requires multiple source files to be reproduced
> + should you attach an archive. Otherwise, the uploaded individual source file
> + or diff should contain the minimal source code needed to reproduce the bug.
> + In any case, make sure the above are included in the body of your bug report
> + as plain text, even if needlessly duplicated as part of an archive.
> +
> +* Please try to reproduce the bug on the current Git master. If it is not
> + reproducible on the Git master, you should figure out if the bug was already
> + fixed. You can search the existing bugs once again, ask on the
> + :r:list:`users`, or do a Git bisect to find a commit which fixed the bug.
> +
> +* Include only information relevant to the bug.
> +
> +* Write separate bug reports for different bugs.
> +
> +* Select a *Type* for the ticket. Use ``defect`` for a bug. Note ``infra`` is
> + used to report issues with the RTEMS servers at OSUOSL.
> +
> +* Select a *Version* for the ticket. This should be the first RTEMS version
> + which is affected by this bug. If this is the current Git master branch use
> + the version of the next release. Please provide the exact version of RTEMS
> + in the description. If you use an RTEMS release, then the release number.
> + If you use a Git clone, then the commit hash. The commit hash should be
> + present in an RTEMS Project repository. Commit hashes of private branches
> + are not interesting.
> +
> +* Select a *Component* for the ticket. Use ``unspecified`` if you are unsure.
> +
> +* Select a *Severity* for the ticket.
> +
> +* The fields *Milestone* and *Priority* will be most likely set by an RTEMS
> + maintainer.
> +
> +* You can relate your new bug to existing bugs through the *Blocked by* and
> + *Blocking* fields.
> +
> +When you have checked that your report meets the criteria for a good bug
> +report, please click on the ``Create ticket`` button to submit it to the RTEMS
> +Project ticket system.
> +
> +If you fail to supply enough information for a bug report to be reproduced,
> +someone will probably ask you to post additional information. In this case,
> +please post the additional information and not just to the person who requested
> +it, unless explicitly told so.
> +
> +Nobody Fixes my Bug
> +===================
> +
> +Sometimes, you may notice that after some time your bug report gets no
> +attention and the bug is not magically fixed. This may have several reasons
> +
> +* the bug report is incomplete or confusing,
> +
> +* the target hardware is not available to others,
> +
> +* the bug is not reproducible on the Git master,
> +
> +* the bug is not reproducible at all,
> +
> +* the RTEMS version is quite old and no longer used by RTEMS maintainers,
> +
> +* fixing the bug has a low priority for others.
> +
> +Please note that you do not have a service contract with the RTEMS Project.
> +The RTEMS Project is run by volunteers and persons which take care about how
which -> who
> +RTEMS performs in their application domain. If your bug does not affect the
> +interest of someone else, then you should try to fix the bug on your own, see
> +the :ref:`Contributing` guidelines. To change the priorities of others with
> +respect to your bug, you may refer to the :ref:`SupportCommercial`.
> diff --git a/user/support/contrib.rst b/user/support/contrib.rst
> index 11c6350..29c554d 100644
> --- a/user/support/contrib.rst
> +++ b/user/support/contrib.rst
> @@ -6,6 +6,8 @@
>
> .. index:: community; developers
>
> +.. _Contributing:
> +
> Contributing
> ************
>
> diff --git a/user/support/support-commercial.rst b/user/support/support-commercial.rst
> index d3aebaa..665426b 100644
> --- a/user/support/support-commercial.rst
> +++ b/user/support/support-commercial.rst
> @@ -4,6 +4,8 @@
>
> .. index:: support; commercial
>
> +.. _SupportCommercial:
> +
> Commercial Support Services
> ***************************
>
> --
> 2.16.4
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
More information about the devel
mailing list