Document how to check out asf-site on case-insensitive file systems

[mootari]

I lost some time trying to figure out why git kept showing files in the asf-site branch as modified immediately after checkout, until I finally realized that some paths exist both as lowercase and mixed-case. I think a few additions to the readme can help avoid that kind of friction for others.

Tasks:

• for macOS, briefly describe how to create a sparse image to clone into, ideally as a terminal command
• give an example for a shallow clone of the asf-site branch to avoid pulling the entire history

[mootari]

... I meant to assign this one to myself, but apparently I can't. 🤔

[kou]

I've assigned you.

Could you share the error message you got?

[mootari]

No error, you just end up with a bunch of modified files because the lowercase version also replaces the mixed-case one. E.g., with

docs/python/generated/pyarrow.Array.html
docs/python/generated/pyarrow.array.html

docs/python/generated/pyarrow.Array.html will be marked as modified immediately after checkout, showing the contents of docs/python/generated/pyarrow.array.html instead.

Presumably the same problem exists on Windows outside of WSL.

[kou]

Ah, OK.
https://arrow.apache.org/docs/python/generated/pyarrow.array.html and
https://arrow.apache.org/docs/python/generated/pyarrow.Array.html are conflicted on case insensitive file system.

@AlenkaF Can we avoid the conflict?

[AlenkaF]

This really is cumbersome, I agree!

Can we avoid the conflict?

I do not think so. Sphinx generates filenames for Python objects (like classes, functions) based on their fully qualified names so pyarrow.Array and pyarrow.array among others can not be changed neither can we leave any of them out from the API docs.

I think the best way is to document creating a sparse image and a shallow clone as suggested in the issue desciption.

[amoeba]

For patch contributors, I think documenting how to do a sparse checkout is an interesting option. When I'm doing larger PRs, such as for releases, I either use a VM or (more often) just boot and SSH into my Linux machine.