Engineering notes

Conventions

Things settled once so they stop being settled weekly.

Incident writeups

Timeline, what actually happened, what we are changing. Action items that are not done say they are not done. A writeup with every item closed on the day of publication is usually a writeup that stopped short.

Design docs

Circulated when they are ready to be argued with, not when they are agreed. Status is where the argument is, not whether code exists. Open questions stay in the doc after it ships, because the question that was hard to answer is the one someone will re-ask in a year.

Releases

Calendar versioned, YYYY.M.patch. The release notes on the console are the record; this host carries the reasoning behind anything that needed some.

Ownership

Every scheduled job, every destination, and every design doc has an owner recorded by initials. The scheduler migration is the argument for the field — three schedules could not be interpreted without asking a person, and two of those people had to be found by reading commit history.