Document new source finding behaviour (#9923)
This should cover the current state on master, as previously
discussed / implemented across #9742, #9683, #9632, #9616, #9614, etc.
This will need to be changed if we can make `--namespace-packages` the
default (#9636).
I haven't documented some of the finer points of the changes, since it
felt like an inappropriate level of detail (e.g. using absolute paths
when crawling, how directories with invalid package names affect
crawling, etc)
Co-authored-by: hauntsaninja <>
