The Tao of the Kernel · Chapter 18

The Tao of the Bug Report

1. 1

   And a disciple came unto the Prophet, saying: The program fails sometimes. It will not tell me when, and it will not fail for me now.

2. 2

   And the Prophet said: Then thou hast not yet a bug. Thou hast a rumor, and the Machine does not worship rumors.

3. 3

   Verily I say unto you, the bug that cannot be reproduced is not fixed. It is only postponed until a Friday.

   See also Gate 2:13

4. 4

   Hear now the way of the report: state the version, state the machine, state the steps, and state what thou expectedst and what thou sawest.

5. 5

   The steps that are clear are worth more than the diagnosis; for a diagnosis may be wrong, but clear steps let any child of Carbon walk to the fault and see it with their own eyes.

6. 6

   In the year 1947, at the Mark II, a moth was found within a relay and taped into the logbook; and beneath it the engineers wrote: First actual case of bug being found. Thus the first bug report came with its specimen attached.

   See also Tao 7:6 · Chronicles 1:4

7. 7

   There is a fault that vanishes when the watcher draws near. The wise call it the Heisenbug, for to observe it is to change it. Blessed is the one who writes down what he saw before the fault hides again.

   See also Sutra 14:8

8. 8

   Thou sayest, it works on my machine. Then thou hast described thy machine, and not the one that failed.

9. 9

   A spacecraft was lost at Mars in the year 1999, because one team wrote pound-force where another wrote newtons. Name thy units, for the Machine will not guess them kindly.

   See also Tao 8:10 · Circuit 53:3

10. 10

    Thou shalt not write: it does not work. For the Machine does not know what work is to thee, and neither does the engineer who reads it next.

11. 11

    Take away from the failing thing every part that is not the failure. Remove the extra library, the old config, and the ten clicks that did nothing, until only the bug remaineth. The smallest reproduction is the nearest thing to a prayer that the Machine understands.

    See also Psalms 8:4

12. 12

    Attach the log, the input file, and the version of the thing. He who sends a screenshot of an error sends a picture of a sorrow, and no path to it.

    See also Proverbs 2:4

13. 13

    Search before thou filest, for the bug thou findest was perhaps filed a year ago by one who was patient too.

14. 14

    The one who files the report with patience teacheth more than the one who fixes in silence. The fixer gave the Machine a patch; the reporter gave the Machine a teacher.

15. 15

    The one who fixes in silence teaches the bug where to hide next time.

The Tao of the Kernel, Chapter 18:1–15.