cherry picked @jgrandguillaume's porting notes

@jgrandguillaume's branch was not mergeable as is, but the porting notes are interesting.