1.. _bug_reporting:
2
3Bug Reporting
4##############
5
6To maintain traceability and relation between proposals, changes, features, and
7issues, it is recommended to cross-reference source code commits with the
8relevant GitHub issues and vice versa.
9Any changes that originate from a tracked feature or issue should contain a
10reference to the feature by mentioning the corresponding issue or pull-request
11identifiers.
12
13At any time it should be possible to establish the origin of a change and the
14reason behind it by following the references in the code.
15
16Reporting a regression issue
17****************************
18
19It could happen that the issue being reported is identified as a regression,
20as the use case is known to be working on earlier commit or release.
21In this case, providing directly the guilty commit when submitting the bug
22gains a lot of time in the eventual bug fixing.
23
24To identify the commit causing the regression, several methods could be used,
25but tree bisecting method is an efficient one that doesn't require deep code
26expertise and can be used by every one.
27
28For this, `git bisect`_ is the recommended tool.
29
30Recommendations on the process:
31
32* Run ``west update`` on each bisection step.
33* Once the bisection is over and a culprit identified, verify manually the result.
34
35.. _git bisect:
36   https://git-scm.com/docs/git-bisect
37