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