.. _bug_reporting:


Bug Reporting
################

Check you have a bug!
=======================

Are you using the latest version of |popy|? It is possible that the bug you are encountering has already been fixed. Examine the :ref:`release_notes`. 

It might be worth upgrading |popy| anyway, to see if the bug gets fixed. All |popy| end user :ref:`licences` allow free upgrades to the latest version. 

Have you managed to reproduce the bug reliably? Preferably on more than one machine. Sometimes the process of reproduction reveals an easy solution.

Note that often |popy| throws an error due to a user error in the input script file. This is |not| classed as a bug. However if the error message is unclear and confusing, that is a bug!

Bug Report Advice
====================

Three elements that help produce a good bug report, are as follows:-

Steps to reproduce
-------------------
    
It is important that the developers can reproduce the bug, otherwise the bug **cannot** be fixed! It is useful to include **all** details, |eg| Operating system and current version of |popy|. The output of :ref:`popy_info` is very helpful. Also any input script files and data sets. If you can reproduce the problem on a small example that fails quickly, that is also very helpful.

Note, confidentiality may prevent you from sharing your original data with us. In this case you may consider:-

* Renaming the data header file to remove context
* Add random noise to your data (check the bug still occurs)
* Removing unused columns and rows (check the bug still occurs)
* Creating a new data set using a :ref:`gen_script`, that exhibits the same bug.

It is helpful to use a zip utility, so we can easily set up your files and reproduce the bug from an email. 
    
Expected result
-----------------

State what you expected to happen! 

Sometimes this is obvious. For example if |popy| crashes mid run. However sometimes it is more subtle, for example, you expected |popy| to give an answer much closer to a ground truth value for a particular model and data set.

Actual result
----------------

Clearly state what actually happened. Reporting any error messages is particularly vital. Note, that a |popy| program typically produces a log file like this:-

.. code-block:: console

    my_script.pyml.run.main.log

However if a runtime error occurs an additional log file is created as follows:-

.. code-block:: console

    my_script.pyml.run.error.log
 
Reporting the bug
===================

Currently |popy| does not have a formal bug tracking system (it may do in the near future), so for now email your bug to:-

.. parsed-literal::

    |email|
  
We will endeavour to respond quickly with a time estimate of how long it will take to fix the bug.

If the bug is serious enough, we will create a new |popy| binary as quickly as possible, otherwise the bug will be fixed in the next planned release for |popy|.



    
    

