In Docs: clarify BUILD vs. BUILD.bazel

[davidstanke]

One can use either BUILD or BUILD.bazel as the filename for config files. AIUI, the preferred name is BUILD.bazel (because why? because this?) but the docs mostly reference BUILD. Can we update the docs to use the preferred version, as well as adding information about which one is preferred, and why?

[ixdy]

before commenting on that issue, I also confirmed that bazel seems to prefer BUILD.bazel; if you have a BUILD.bazel file and a BUILD file, it'll ignore the latter.

[ixdy]

for cross-reference, the original BUILD.bazel discussion was in #552.

[tualeron]

This will be a massive search-and-replace effort on both docs.bazel.build and GitHub. Prioritizing low unless someone objects.

[mhsmith]

It doesn't need to be searched-and-replaced, but it does need to be mentioned as an alternative in case an existing project has a name conflict. Right now the BUILD.bazel name doesn't seem to be mentioned on docs.bazel.build at all, except on the Android NDK page, where it's used without explanation.

[pauldraper]

I too am confused about which is conventional, or the pros/cons.

What will be least confusing to contributors to my OSS project?

(And for that matter, why does Bazel need both?)

[katre]

General advice, I think, should be to always use BUILD.bazel, unless you have an existing codebase that doesn't.

Bazel has both for this reason: we have a very large codebase that uses only "BUILD" files, but there are many legitimate cases where users cannot name files "BUILD", and so they need an alternative.

[laurentlb]

BUILD.bazel is more explicit. If you have a BUILD.bazel file on your GitHub repository, users can understand what it is more easily (or they can find out easily). It also has less risk of collision.

Downside: it's more characters to type.