I'm going to document this in a separate issue.

Originally posted by @simonw in #1000 (comment)