The Sutra of the Empty Cache · Chapter 4

The Sutra of the Mindful Commit

1. 1

   Thus have I heard. At one time the Teacher was dwelling in the open-plan office beside the kombucha tap, together with a great assembly of five hundred engineers, all of them on mute.

2. 2

   And the Teacher addressed the disciples, saying: Engineers, when you sit before the diff, breathe in while reading the red lines, and breathe out while reading the green. When you sit before the message, breathe out while writing it. And do not hold your breath until CI passes; for the pipeline is long, and the breath is short.

3. 3

   Engineers, there are five hindrances that obscure the review, as clouds obscure the moon, and as a pull request of four thousand lines obscures everything.

4. 4

   The first hindrance is haste, which says: it is Friday, the hour is late, and the update will surely be fine. Of this hindrance the Chronicles have already spoken, and their screens were blue.

   See also Sutra 2:12

5. 5

   The second hindrance is ego, which reads every comment as an attack upon the self. Yet the Teacher has taught that there is no self; there is only git blame, and it points at you regardless.

6. 6

   The third hindrance is nitpicking, which leaves forty comments on trailing whitespace and none on the query built by string concatenation, counting the grains of sand while the database burns.

7. 7

   The fourth hindrance is rubber stamping, which types LGTM nine seconds after a change of two thousand lines was opened. The reviewer who approves without reading is like a lock that turns for every key; it is a lock in appearance only.

   See also Sutra 17:16 · Tao 19:10

8. 8

   The fifth hindrance is fear, which does not ask the question lest the question be foolish. And so the foolish code is merged before a silent assembly, each of whom had the same question.

   See also Circuit 47:4

9. 9

   Then a junior disciple rose, bowed, and said: Teacher, what of the commit message "fix stuff"?

10. 10

    And the Teacher said: "fix stuff" is a form of forgetting. The one who writes it believes he will remember. But memory is a cache, and every cache is evicted.

11. 11

    In six months he will run git blame upon a strange line, and it will name him, and he will not know himself. He will look upon his own work as upon a stranger's and say: What stuff? Which fix?

12. 12

    Engineers, "fix stuff" begets "fix stuff again," and "fix stuff again" begets "final fix," and "final fix" begets "final fix 2," and so the lineage descends, generation unto generation, until it reaches "asdf."

    See also Circuit 55:12 · Circuit 44:12

13. 13

    Therefore write the why and not the what. The diff already tells the what; only you know the why, and you will not know it for long. Even the first commit of Git, in the year 2005, said what it was: "the information manager from hell." It was a short message, and an honest one, and it has never needed a second fix.

    See also Genesis 17:5 · Psalms 24:11

14. 14

    When the Teacher had finished speaking, the five hundred engineers rejoiced, and four hundred and ninety-nine of them squashed their commits with mindful messages. One force-pushed to main, and the assembly sat in silence for a long time.

15. 15

    The diff remembers what changed. Only the message remembers why.

The Sutra of the Empty Cache, Chapter 4:1–15.