Guidelines for creating meaningful issue reports
================================================
This section gives some started on how to generate useful issues on the
|Gromacs| `issue tracker`_. The information here comes to a large extent
directly from there, to help you in preparing your reports.

What to report
^^^^^^^^^^^^^^
Please only report issues you have confirmed to be caused by |Gromacs| behaving in an
unintended way, and that you have investigated to the best of your ability. If you have
large simulations fail at some point, try to also trigger the problem with smaller test
cases that are more easily debuggable.

Bugs resulting from the use third-party software should be investigated first to make sure
that the fault is in |Gromacs| and not in other parts of the toolchain.

Please do not submit generic issues resulting from system instabilities and systems :ref:`blowing-up`.

What should be included
^^^^^^^^^^^^^^^^^^^^^^^
The report should include a general description of the problem with |Gromacs| indicating
both the expected behaviour and the actual outcome. If the issue causes program
crashes, the report should indicate where the crash happens and if possible
include the stack trace right up to the crash.


All bugs should include the necessary information for the developers to reproduce the errors,
including if needed minimal input files (\*tpr, \*top, \*mdp, etc),
run commands or minimal version of run scripts, how you compiled |Gromacs| and if possible the system architecture.


The emphasis should be on having a *minimal* working example that is easy to follow for the developers, that
does not result in any warnings or errors in itself. If your example generates errors, your issue will likely
not be considered as *real*, or at the minimum it will be much harder to analyse to find the actual issue.


If your inputs are sensitive, then it is possible to create private
`issues <https://gitlab.com/gromacs/gromacs/-/issues/>`_
so that the developer team can have access to solve the problem, while preventing widespread
visibility on the internet.


Supporting the developers
^^^^^^^^^^^^^^^^^^^^^^^^^
In general you should be able to answer questions posed to you by the developers
working on the program, if you want to help them in fixing the bug you found. This may
include things such as explaining run scripts or simulation set-up, as well as
confirming issues with different versions of the program and different combinations
of supported libraries and compilers.


Please refrain from setting things such as target version or deciding on unreasonable priorities. If you decide
to fix the issue on your own, please adhere to the other standards mentioned on the related pages
:ref:`code-formatting` and :ref:`code-commitstyle`.

.. seealso:: :doc:`contribute`

.. _issue workflow:

General issue workflow
^^^^^^^^^^^^^^^^^^^^^^

The general issue workflow is shown in the figure below:

.. image:: redmine-states.png
   :alt:  Sample procedure pathway for reported issues.

Project maintainers will apply
`Status labels <https://gitlab.com/gromacs/gromacs/-/labels?search=status>`__
as the issue is processed.

* `Status::Accepted <https://gitlab.com/gromacs/gromacs/-/issues?label_name%5B%5D=Status%3A%3AAccepted>`__:
  Bug confirmed / Desirable feature.
* `Status::In Progress <https://gitlab.com/gromacs/gromacs/-/issues?label_name%5B%5D=Status%3A%3AIn+Progress>`__:
  Assignee starts to work.
* `Status::Blocked <https://gitlab.com/gromacs/gromacs/-/issues?label_name%5B%5D=Status%3A%3ABlocked>`__: Progress requires feedback or other action.
* `Status::Rejected <https://gitlab.com/gromacs/gromacs/-/issues?label_name%5B%5D=Status%3A%3ARejected>`__:
  Invalid report or not a desirable feature.
* `Status::Fix uploaded <https://gitlab.com/gromacs/gromacs/-/issues?label_name%5B%5D=Status%3A%3AFix+uploaded>`__:
  Merge request is available for review
* `Status::Feedback-wanted <https://gitlab.com/gromacs/gromacs/-/issues?label_name%5B%5D=Status%3A%3AFeedback-wanted>`__: Resolution pending additional feedback or response
* `Status::Resolved <https://gitlab.com/gromacs/gromacs/-/issues?label_name%5B%5D=Status%3A%3AResolved>`__:
  The issue will be closed if there is no further discussion.

.. Text below is stolen from the old |Gromacs| web page

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

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

.. 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 do not 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.

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

.. 4. Please do not set a target version unless you are the person working on the bug.

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

.. 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 in the discussion forums, follow a long discussion about what you want to do, and then decipher scripts to understand what happened.
