<div dir="ltr">Dear folks<div><br></div><div>I'm asked how to write a bug report for ndn-cxx, NFD, or ndn-tools. Here's my take on this topic.</div><div><br></div><div>The purpose of a bug report is to alert code maintainer / developer about a potential problem in the codebase.</div><div>In most cases, a bug report should contain the following information:</div><div><br></div><div><b>Environment</b></div><div>What operating system (and version) are you on? Example: "Ubuntu 16.04 32-bit"; "OS X 10.10". This information is optional if the problem occurs on every platform.</div><div>What's the version of your compiler? Example: "gcc 4.8.1". This information is optional if you are using the default compiler (gcc from Ubuntu package, clang in XCode).</div><div>What's the version of the software, and how did you install it? Example: "NFD 0.4.1 installed from Ubuntu PPA". This information is optional if the problem occurs with latest git master version installed from source code.<br></div><div>What's the version of major dependency, and how did you install it? Example: "Boost 1.58.0 installed from HomeBrew". This information is optional if the problem is agnostic to dependency version, and the dependency is installed from the default software source (such as Ubuntu package).</div><div><br></div><div><b>Steps to reproduce</b></div><div>A good bug report should help developers to <u>reproduce</u> the problem. If a developer follows the steps you gave exactly, she should be able to see the same behavior as you do.</div><div>If you are trying to use a program, steps to reproduce should include (1) any configuration option you have changed (2) the exact commands you are executing (3) timing of the commands, if relevant.</div><div>If you are trying to use an API, steps to reproduce should include a code snippet that uses the API.</div><div>If the bug involves network transmission on a topology, give a diagram of a minimal topology where the problem occurs.</div><div>If the bug involves a software component written or modified by you, provide the source code of that software (or a stripped down version of it), so that a developer can use the same program as you.</div><div><br></div><div><b>Expected result & Actual result</b></div><div>What are you trying to achieve or expecting to see? What actually happened?<br></div><div>Example:</div><div>Expected: code builds successfully. Actual: compile error XXXX (paste the complete error message).</div><div>Expected: function R returns true. Actual: function R returns false.</div><div>Expected: Interest counter is greater than 80. Actual: Interest counter is 0.</div><div>Expected: Data payload appears on the console. Actual: nothing appears on the console.</div><div><br></div><div><b>Diagnostics information</b></div><div>For build error, paste the <u>complete error message</u>.</div><div>For NFD, if you suspect the bug is within a certain module, set loglevel of this module to TRACE, capture <u>NFD log</u> and upload as an attachment.</div><div>For NFD bug involving network transmission, capture a Wireshark/<u>tcpdump trace</u> and upload as an attachment.</div><div>For bugs involving a program crash, make sure you have debug symbols installed (already installed if you built the program from source code; otherwise, install *-dbg packages from Ubuntu PPA), and then run the software within gdb; when crash occurs, type `<u>bt full</u>` (not just `bt`) and upload the output text as an attachment.</div><div>For bugs involving a memory leak, make sure you have debug symbols installed, run the software within <u>valgrind</u>, and upload the output as an attachment.</div><div><br></div><div><br></div><div>Before you report a bug, search the relevant problem in nfd-dev mailing list and on Redmine, to see whether others have experienced the same problem. If you find a report about a similar problem, it's usually unnecessary to report a duplicate bug; instead, press the Watch button so that you can get updates on the progress. If a workaround is already given on the existing report, try it in your environment, and post a note under the report on whether the workaround helps or not. If the existing report seems relevant but is not exactly the same, you can also post a note under the report about your exact problem (typically, the different environment).</div><div>Before you post a bug report or note on Redmine, make sure to use the correct Markdown format, and press the Preview button to confirm everything renders correctly.</div><div>If you are unsure about whether a behavior is a bug or you are using the software/API incorrectly, you can either post a message to nfd-dev mailing list, or report it as a bug on Redmine. In either case, the report should contain all information above, so that a developer can help you.</div><div>It's recommended to address all bug reports (or suspected bugs) to nfd-dev or Redmine, not to individual developers. This allows others who experience the same problem to search for and find your report, so as to save time for everyone.</div><div><div><br></div><div>This article is part of "HOWTOs for n00b" series. You may find other articles in this series on <a href="http://redmine.named-data.net/projects/nfd/wiki">NFD wiki</a> under developer resources.</div><div><br></div><div>Yours, Junxiao</div></div></div>