Portfolio · Writing
Pull Request Descriptions
A pull request isn't a formality. It's usually the one moment when everybody who will have to live with a change is actually looking at it, so it's a good place to teach something: what changed, why it changed, how to review it, and what we would all need to do differently afterward.
Each one needs a different shape. Sometimes the reviewer needs a page of background before the diff will make any sense at all. Other times what helps most is a walk through the files in a particular order, or an honest account of a trade-off I wasn't sure about. I try to work out which of those a change needs before I start writing.
Every description here was written by hand, with no AI assistance.
These come from the frontend platform work at InterNations. It's a large single-page app, and we carried it through a long series of migrations: a global store, a router, a strict TypeScript flag, and two major framework versions.
Most of them were changes that nobody had asked for and that everybody would then have to live with. That turns out to be a particular kind of writing problem. Before you can ask somebody to accept a change, you have to convince them that the problem was worth solving in the first place.
The code is private and will stay that way. What's below is the writing on its own, reproduced as the team saw it, with internal links flattened to plain text.
Architecture proposal
SPA global store with Zustand
Making the case for a global store in an app that had gotten by without one.
Teaching document
Satisfy the noUncheckedIndexedAccess option
One reference document, written once and reused across 28 pull requests.
Migration guide
Upgrade react-query to v5
Upgrading react-query a major version, with the traps mapped out first.
9 more
Teaching document
Enable TypeScript option noUncheckedIndexedAccess
Turning on a strict TypeScript flag after months of clearing the way for it.
Convention change
closeDialog() only closes one specific dialog
A dialog API that closed the wrong dialog, and the house style that came out of fixing it.
How to review it
App Router migration prep: Create structure for main route group in @app folder
Splitting a framework migration into pieces a person can actually review.
Concept primer
Referential stability 1/5: useExperiment
Explaining a subtle React concept before asking anybody to go and apply it.
Findings and solution
Overhaul the useMediaQueries hook
Why you can no longer detect the screen size in JavaScript, and what to do instead.
Problem and solution
Defining experiments in Route definitions, part 1/2
Pulling experiment logic out of several files and into the route definitions.
Adoption guide
Remove Realms and Pages Router
Deleting an abstraction we built ourselves, and writing down what replaces it.
Deprecation guidance
Enhanced router (1/8) New hook useINRouter()
One routing hook to replace three, delivered across eight pull requests.
Tool introduction
Checkpoint end-user performance testing tool and task runner
A performance testing tool for the team, plus an invitation to add to it.
Back to the rest of the portfolio.