[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