docs/dev-manual/reportstyle.rst

   1 Guidelines for creating meaningful redmine issue reports
   2 ========================================================
   3 This section gives some started on how to generate useful issues on the
   4 |Gromacs| `redmine issue tracker`_. The information here comes to a large extent
   5 directly from there, to help you in preparing your reports.
   6
   7 .. _redmine issue tracker: https://redmine.gromacs.org
   8
   9 What to report
  10 ^^^^^^^^^^^^^^
  11 Please only report issues you have confirmed to be caused by |Gromacs| behaving in an
  12 unintended way, and that you have investigated to the best of your ability. If you have
  13 large simulations fail at some point, try to also trigger the problem with smaller test
  14 cases that are more easily debuggable.
  15
  16 Bugs resulting from the use third-party software should be investigated first to make sure
  17 that the fault is in |Gromacs| and not in other parts of the toolchain.
  18
  19 Please don't submit generic issues resulting from system instabilities and systems :ref:`blowing-up`.
  20
  21 What should be included
  22 ^^^^^^^^^^^^^^^^^^^^^^^
  23 The report should include a general description of the problem with |Gromacs| indicating
  24 both the expected behaviour and the actual outcome. If the issue causes program
  25 crashes, the report should indicate where the crash happens and if possible
  26 include the stack trace right up to the crash.
  27
  28
  29 All bugs should include the necessary information for the developers to reproduce the errors,
  30 including if needed minimal input files (\*tpr, \*top, \*mdp, etc),
  31 run commands or minimal version of run scripts, how you compiled |Gromacs| and if possible the system architecture.
  32
  33
  34 The emphasis should be on having a *minimal* working example that is easy to follow for the developers, that
  35 does not result in any warnings or errors in itself. If your example generates errors, your issue will likely
  36 not be considered as *real*, or at the minimum it will be much harder to analyse to find the actual issue.
  37
  38
  39 If your inputs are sensitive, then it is possible to create private Redmine issues so that the
  40 developer team can have access to solve the problem, while preventing widespread
  41 visibility on the internet.
  42
  43
  44 Supporting the developers
  45 ^^^^^^^^^^^^^^^^^^^^^^^^^
  46 In general you should be able to answer questions posed to you by the developers
  47 working on the program, if you want to help them in fixing the bug you found. This may
  48 include things such as explaining run scripts or simulation set-up, as well as
  49 confirming issues with different versions of the program and different combinations
  50 of supported libraries and compilers.
  51
  52
  53 Please refrain from setting things such as target version or deciding on unreasonable priorities. If you decide
  54 to fix the issue on your own, please adhere to the other standards mentioned on the related pages
  55 :ref:`code-formatting` and :ref:`code-commitstyle`.
  56
  57
  58 General issue workflow
  59 ^^^^^^^^^^^^^^^^^^^^^^
  60
  61 The general issue workflow is shown in the figure below:
  62
  63 .. image:: redmine-states.png
  64    :alt:  Sample procedure pathway for issues reported in redmine.
  65
  66
  67 .. Text below is stolen from the old Gromacs web page
  68
  69 .. 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.
  70
  71 .. 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.
  72
  73 .. 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.
  74
  75 .. 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.
  76
  77 .. 4. Please don't set a target version unless you are the person working on the bug.
  78
  79 .. 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.
  80
  81 .. 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.