Fork us on GitHub Follow us on Google+ Follow us on Facebook Follow us on Twitter

Changes between Version 9 and Version 10 of HowToFileABug


Ignore:
Timestamp:
2016-01-10T01:39:24Z (3 years ago)
Author:
Martin Decky
Comment:

improve grammar

Legend:

Unmodified
Added
Removed
Modified
  • HowToFileABug

    v9 v10  
    1 = How to file a bug =
     1= How to File a Bug =
    22
    3 As in any other complex software system, there will inevitably be bugs in the HelenOS source code (unless we can formally prove the opposite). It is therefore essential for people who run into them to make sure the bug is actually known to the developers and that all potentially relevant information that can help to root-cause the bug is available. This is best achieved by [/newticket filing a ticket] in our [report:1 bug tracking database].
     3As in any other complex software system, there will inevitably be bugs in the HelenOS source code (unless we can formally prove the opposite). It is therefore essential for people who run into them to make sure the bug is actually known to the developers and that all potentially relevant information that can help to point to the root cause of the bug is available. This is best achieved by [/newticket filing a ticket] in our [report:1 bug tracking database].
    44
    55Writing bug reports is by far not that trivial as it may initially seem. Quite the contrary. Writing really good bug reports takes some effort and needs some practice, but the reward is high.  The ticket owner can then focus on solving the bug itself rather than figuring out all the information and circumstances that lead to it. Below follows a list of tips for filing the most useful bug reports.
    66
    7   * Make sure the bug is not a duplicate of some other bug
    8     * If it is, consider improving the original bug report by providing additional data, but don't file any new ticket
     7  * Make sure the bug is not a duplicate of some other bug.
     8    * If it is, consider improving the original bug report by providing additional data, but don't file a new ticket.
    99    * If in doubt, then please do file a new ticket.
    10   * Pick a descriptive ```Summary```
     10  * Pick a descriptive ```Summary```.
    1111    * '''bad''': ''HelenOS has bugs''
    1212    * '''good''': ''page_ht_lock mutex taken while tlblock spinlock held''
    13   * Avoid creating multi-tickets
     13  * Avoid creating multi-tickets.
    1414    * '''bad''': ''Fix problem XYZ on amd64, arm32, ia32, ia64, mips32, ppc32 and sparc64''
    15     * Instead, consider filing separate tickets for all of the above architectures. This will make it easier to track progress on each architecture separately
    16   * Categorize the new bug using fitting ```Type```, ```Component``` and ```Version``` fields
    17   * In the first comment section, provide a concise and complete problem statement
    18     * Say what deviation from the expected behavior you observe
    19     * Briefly say what you think the expected behavior should be
    20     * Include instructions and/or code fragments to reproduce the problem or state that the problem is not easily reproducible
    21     * If you set the ```Version``` field to ''mainline'', provide the exact changeset in which the bug was observed
    22       * If the bug was observed in multiple changesets, specify the first one in which the problem was observed
     15    * Instead, consider filing separate tickets for all of the above architectures. This will make it easier to track progress on each architecture separately.
     16  * Categorize the new bug using fitting ```Type```, ```Component``` and ```Version``` fields.
     17  * In the first comment section, provide a concise and complete problem statement.
     18    * Say what deviation from the expected behavior you observe.
     19    * Briefly say what you think the expected behavior should be.
     20    * Include instructions and/or code fragments to reproduce the problem or state that the problem is not easily reproducible.
     21    * If you set the ```Version``` field to ''mainline'', provide the exact changeset in which the bug was observed.
     22      * If the bug was observed in multiple changesets, specify the first one in which the problem was observed.
    2323    * Provide reasonable details about the hardware of the target system, such as:
    2424      * the processor architecture, if not already clear from the ```Component``` field
    2525      * number of processors
    2626      * name and version of the simulator/virtualizer, if the target system is a simulated machine
    27     * Provide reasonable details about HelenOS configuration
    28       * consider attaching Makefile.config from the root of the HelenOS tree
    29       * Say whether HelenOS was built with the recent [source:mainline/tools/toolchain.sh toolchain.sh] script or not
     27    * Provide reasonable details about HelenOS configuration.
     28      * Consider attaching Makefile.config from the root of the HelenOS tree.
     29      * Say whether HelenOS was built with the recent [source:mainline/tools/toolchain.sh toolchain.sh] script or not.
    3030        * Building with native toolchain is strongly discouraged. Please make sure that the bug is still reproducible using the supported toolchain before filing the bug. If you really think that logging a bug which is only reproducible with the native toolchain is justifiable, then please state versions of the used compiler, assembler and linker.
    31     * If there is a stack trace associated with the bug, paste it into the bug report
    32       * Compressing and attaching a screenshot with the stack trace (and other messages) may be an option if the stack trace cannot be easily copied and pasted
    33       * In case there is a core dump generated for a crashing task, compress it and attach it to the ticket
    34       * Alternatively, attach the compressed binary itself (kernel.raw or the respective uspace binary). Note that attaching .disasm files is problematic as these files are usually much bigger than the respective binaries themselves (even when compressed)
    35     * If there are some terminal or console messages of interest such as warnings or errors, mention those in the bug report
     31    * If there is a stack trace associated with the bug, paste it into the bug report.
     32      * Compressing and attaching a screenshot with the stack trace (and other messages) may be an option if the stack trace cannot be easily copied and pasted.
     33      * In case there is a core dump generated for a crashing task, compress it and attach it to the ticket.
     34      * Alternatively, attach the compressed binary itself (kernel.raw or the respective user space binary). Note that attaching .disasm files is problematic as these files are usually much bigger than the respective binaries themselves (even when compressed).
     35    * If there are some terminal or console messages of interest such as warnings or errors, mention those in the bug report.