Writing a Kev pull request

A Kev PR is read by three people: the reviewer today, someone reading git log next year to learn why a number changed, and a reader who is not an ML researcher (an engineer integrating the API, a student, a curious normie). Write for the third one. If the description only makes sense to whoever wrote the diff, it is a changelog, not a PR.

The models for this are Andrew Clark (acdlite) and Sebastian Markbåge (sebmarkbage) on facebook/react before 2023. Their descriptions read as short essays: problem first, mechanism second, what could go wrong third, what was left out last. Read a few before writing a big one: