docs/dev-manual/reportstyle.rst

   1 Guidelines for creating meaningful issue reports
   2 ================================================
   3 This section gives some started on how to generate useful issues on the
   4 |Gromacs| `issue tracker`_. The information here comes to a large extent
   5 directly from there, to help you in preparing your reports.
   6
   7 What to report
   8 ^^^^^^^^^^^^^^
   9 Please only report issues you have confirmed to be caused by |Gromacs| behaving in an
  10 unintended way, and that you have investigated to the best of your ability. If you have
  11 large simulations fail at some point, try to also trigger the problem with smaller test
  12 cases that are more easily debuggable.
  13
  14 Bugs resulting from the use third-party software should be investigated first to make sure
  15 that the fault is in |Gromacs| and not in other parts of the toolchain.
  16
  17 Please don't submit generic issues resulting from system instabilities and systems :ref:`blowing-up`.
  18
  19 What should be included
  20 ^^^^^^^^^^^^^^^^^^^^^^^
  21 The report should include a general description of the problem with |Gromacs| indicating
  22 both the expected behaviour and the actual outcome. If the issue causes program
  23 crashes, the report should indicate where the crash happens and if possible
  24 include the stack trace right up to the crash.
  25
  26
  27 All bugs should include the necessary information for the developers to reproduce the errors,
  28 including if needed minimal input files (\*tpr, \*top, \*mdp, etc),
  29 run commands or minimal version of run scripts, how you compiled |Gromacs| and if possible the system architecture.
  30
  31
  32 The emphasis should be on having a *minimal* working example that is easy to follow for the developers, that
  33 does not result in any warnings or errors in itself. If your example generates errors, your issue will likely
  34 not be considered as *real*, or at the minimum it will be much harder to analyse to find the actual issue.
  35
  36
  37 If your inputs are sensitive, then it is possible to create private `issues`_ so that the
  38 developer team can have access to solve the problem, while preventing widespread
  39 visibility on the internet.
  40
  41
  42 Supporting the developers
  43 ^^^^^^^^^^^^^^^^^^^^^^^^^
  44 In general you should be able to answer questions posed to you by the developers
  45 working on the program, if you want to help them in fixing the bug you found. This may
  46 include things such as explaining run scripts or simulation set-up, as well as
  47 confirming issues with different versions of the program and different combinations
  48 of supported libraries and compilers.
  49
  50
  51 Please refrain from setting things such as target version or deciding on unreasonable priorities. If you decide
  52 to fix the issue on your own, please adhere to the other standards mentioned on the related pages
  53 :ref:`code-formatting` and :ref:`code-commitstyle`.
  54
  55
  56 General issue workflow
  57 ^^^^^^^^^^^^^^^^^^^^^^
  58
  59 The general issue workflow is shown in the figure below:
  60
  61 .. image:: redmine-states.png
  62    :alt:  Sample procedure pathway for reported issues.
  63
  64
  65 .. Text below is stolen from the old Gromacs web page
  66
  67 .. Before opening a new issue, take a minute and make it easy for everybody else (in particular the developers!) to help you - that way you are much more likely to get a solution to your problem.
  68
  69 .. 1. Isolate the problem as far as possible. If you submit a huge tpr file that sometimes fails after a million steps, it is pretty much guaranteed that nobody is going to debug it.
  70
  71 .. 2. Upload a single small example of how a simulation (or some other GROMACS program) crashes. This should ideally be a single (small) conf.gro file, topol.top, and grompp.mdp. Make sure that your input files are processed without warnings for the GROMACS version you are submitting a bug report for, and don't rely on some large external force field or long script. In most cases these additional files and warnings are of course completely unrelated to the problem, but particularly in that case you are helping others a lot by not having to take them into account.
  72
  73 .. 3. Provide a very concise report of exactly what commands you used (so it can be reproduced), what behavour you expected, and what you got.
  74
  75 .. 4. Please don't set a target version unless you are the person working on the bug.
  76
  77 .. 5. If you set the priority to "high" as a user, we assume this means you will also prioritize it yourself and provide close to instant feedback and/or help with testing. If you are a developer, setting the priority to "high" means you are working on fixing this bug yourself. In other words: Please do not set the priority to "high" just to get somebody else to fix it faster.
  78
  79 .. At some point it might be necessary to have more files (including those large scripts) to debug the problem, but you are much more likely to get help if developers do not have to search for files in several different places, read up on a number of threads on the mailing list, follow a long discussion about what you want to do, and then decipher scripts to understand what happened.