Bug Reporting

.. _bug_reporting:

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

To maintain traceability and relation between proposals, changes, features, and
issues, it is recommended to cross-reference source code commits with the
relevant GitHub issues and vice versa.
Any changes that originate from a tracked feature or issue should contain a
reference to the feature by mentioning the corresponding issue or pull-request
identifiers.

At any time it should be possible to establish the origin of a change and the
reason behind it by following the references in the code.

Reporting a regression issue
****************************

It could happen that the issue being reported is identified as a regression,
as the use case is known to be working on earlier commit or release.
In this case, providing directly the guilty commit when submitting the bug
gains a lot of time in the eventual bug fixing.

To identify the commit causing the regression, several methods could be used,
but tree bisecting method is an efficient one that doesn't require deep code
expertise and can be used by every one.

For this, `git bisect`_ is the recommended tool.

Recommendations on the process:

* Run ``west update`` on each bisection step.
* Once the bisection is over and a culprit identified, verify manually the result.

.. _git bisect:
   https://git-scm.com/docs/git-bisect