[PATCH] user: Improve bug report section

Joel Sherrill joel at rtems.org
Tue Aug 6 19:22:56 UTC 2019


FWIW the pages converted by the high school students during Google Code-in
to be in the SW Eng Guide were from Wiki pages which ultimately need to be
deleted. There needs to be a pass to compare Rest version against the Wiki
version and then delete the Wiki version. And anytime a Wiki document is
deleted,
it is very likely links on other pages (including rtems.org top) need to be
changed.



On Tue, Aug 6, 2019 at 1:30 PM Gedare Bloom <gedare at rtems.org> wrote:

> 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
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20190806/b072911e/attachment-0002.html>


More information about the devel mailing list