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