Skip to content

Filing bug reports

Jean-Noël Grad edited this page Feb 4, 2021 · 2 revisions

If you discover a bug in ESPResSo, please let the developers know, so that they can fix it in the next release. The following sections explain how to file a bug report.

Before reporting a bug

Sometimes, bugs are already fixed in more recent version of ESPResSo, or in the development branch. You can save a lot of time by checking if the bug was already reported:

  • check the release notes to see if the behavior has been fixed in a more recent versions of ESPResSo; you can get the version of ESPResSo with the shell command ./pypresso -c "import espressomd.version as v; print(v.friendly())"
  • check the release notes of upcoming releases in the GitHub wiki, which are listed under "Planned releases" in the navigation bar
  • query the bug in the ESPResSo issue tracker to check whether the bug has already been reported
  • check the ESPResSo user's mailing list (Archives)
You may also consider activating C++ assertions by updating the build directory with cmake . -DCMAKE_BUILD_TYPE=RelWithAssert and rebuilding ESPResSo. The resulting binaries will run slightly slower, but will produce an error message if a runtime exception was found, for example a division by zero or an access out of bounds.

Reporting a bug

To help us finding the bug in the code, please open a ticket or send an e-mail to the mailing list.

Make sure to provide us with the following information:

  • In what component of ESPResSo did you find the bug?
  • In what version did you find the bug?
    • For an ESPResSo release, provide us with the exact release using ./pypresso -c "import espressomd.version as v; print(v.friendly())"
    • For the development branch, provide us with the commit SHA using git log --pretty=oneline -1
  • Please give all possible information that you can provide, but at least the following:
    • The script that failed
      • If the script comes from ESPResSo, give us its filepath
      • For custom scripts, please remove as much of the code that is not relevant to reproduce the bug, and attach that minimal working example to the GitHub issue or email
    • All relevant error messages
      • The CMake output: it contains valuable information about your libraries
      • The pypresso error message or backtrace; please compile ESPResSo in debug mode to help us track the source of the error
        • You can usually get a backtrace by updating the build directory with cmake . -DCMAKE_BUILD_TYPE=Debug and rebuilding ESPResSo
        • In case of a fatal exception that shows no backtrace, try running the script with GDB to show where the exception is thrown:
          $> ./pypresso --gdb
          (gdb) catch throw
          (gdb) run
          (gdb) bt
      • Here is a workflow to generate the required information in two files (cmake.log and trace.log) that can be attached to the GitHub issue or email, together with the minimal working example
        cmake --version | tee cmake.log
        cmake .. -DCMAKE_BUILD_TYPE=Debug 2>&1 | tee -a cmake.log
        make -j$(nproc)
        ./pypresso 2>&1 | c++filt | tee trace.log
    • All relevant information about your build environment
      • Your operating system name and version, for example Ubuntu 20.04
      • The file myconfig.hpp that you used, or "default myconfig" if you didn't use one
If your bug report doesn't contain enough information to be actionable, a core developer will ask you to provide more detail.