==========================
Reporting issues and bugs
==========================

----------------------------
Using GitHub to report a bug
----------------------------

Bug reports for Microprobe itself should be submitted via the 
`Microprobe`_ GitHub . GitHub offers **issue** support which allows 
the user to enter information and share it to the developers. 

The first step in filing a report is to determine whether the problem has 
already been reported. The advantage in doing so, aside from saving the 
developers time, is that you learn what has been done to fix it; it may be 
that the problem has already been fixed for the next release, or additional 
information is needed (in which case you are welcome to provide it if you 
can!). To do this, search first for existing issues. 

If the problem you're reporting is not already reported, 
create a new issue at https://github.com/IBM/microprobe/issues. 

To create a new issue, just go to the *Issues* section and click the
*New issue* button. The new issue form has various fields. 
For the "Title" field, enter a **very** 
short description of the problem; less than ten words is good. 

In the "Rich text" field, describe the problem in detail, including what you 
expected to happen and what did happen. Be sure to include whether any 
extension modules were involved, and what hardware and software platform you 
were using (including version information as appropriate) if you
think the problem is related to that. 

Attach any necessary files to be able to reproduce the problem if needed. 
If you found the solution for the problem you can attach the patch in this
section as well. See the section **Submit patches** to check how to create 
patch files.    

In the 'labels' section on the right, select the ones that apply
to the current issue. You can also add any label as you wish to describe
better the problem. 

Each bug report will be reviewed by a developer who will determine what needs 
to be done to correct the problem. You will receive an update each time action 
is taken on the bug.

.. seealso::

   - `How to Report Bugs Effectively <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_
      Article which goes into some detail about how to create a useful bug report.
      This describes what kind of information is useful and why it is useful.

   - `Bug Writing Guidelines <https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines>`_
      Information about writing a good bug report.  Some of this is specific to the
      Mozilla project, but describes general good practices.
      
------------------
Documentation bugs
------------------

If you find a bug in this documentation (typos, ...) or would like to propose 
an improvement (some explanation is not clear, ...), please open a bug issue
in the `Microprobe`_ repository (see instructions below). If you have 
a suggestion how to fix it, include that as well.

.. _`Microprobe`: https://github.com/IBM/microprobe 
