[Nfd-dev] HOWTO write a bug report effectively

Junxiao Shi shijunxiao at email.arizona.edu
Mon May 23 13:22:26 PDT 2016


Dear folks

I'm asked how to write a bug report for ndn-cxx, NFD, or ndn-tools. Here's
my take on this topic.

The purpose of a bug report is to alert code maintainer / developer about a
potential problem in the codebase.
In most cases, a bug report should contain the following information:

*Environment*
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.
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).
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.
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).

*Steps to reproduce*
A good bug report should help developers to *reproduce* the problem. If a
developer follows the steps you gave exactly, she should be able to see the
same behavior as you do.
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.
If you are trying to use an API, steps to reproduce should include a code
snippet that uses the API.
If the bug involves network transmission on a topology, give a diagram of a
minimal topology where the problem occurs.
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.

*Expected result & Actual result*
What are you trying to achieve or expecting to see? What actually happened?
Example:
Expected: code builds successfully. Actual: compile error XXXX (paste the
complete error message).
Expected: function R returns true. Actual: function R returns false.
Expected: Interest counter is greater than 80. Actual: Interest counter is
0.
Expected: Data payload appears on the console. Actual: nothing appears on
the console.

*Diagnostics information*
For build error, paste the *complete error message*.
For NFD, if you suspect the bug is within a certain module, set loglevel of
this module to TRACE, capture *NFD log* and upload as an attachment.
For NFD bug involving network transmission, capture a Wireshark/*tcpdump
trace* and upload as an attachment.
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 `*bt full*` (not just `bt`)
and upload the output text as an attachment.
For bugs involving a memory leak, make sure you have debug symbols
installed, run the software within *valgrind*, and upload the output as an
attachment.


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).
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.
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.
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.

This article is part of "HOWTOs for n00b" series. You may find other
articles in this series on NFD wiki
<http://redmine.named-data.net/projects/nfd/wiki> under developer resources.

Yours, Junxiao
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.lists.cs.ucla.edu/pipermail/nfd-dev/attachments/20160523/b7b6e016/attachment.html>


More information about the Nfd-dev mailing list