Rules_go: To BUILD or to BUILD.bazel, that is the question

[justinsb]

576 renamed BUILD -> BUILD.bazel, so gazelle is now generating BUILD.bazel files. But most/all docs still reference BUILD, not BUILD.bazel, and it's a little confusing to me. I presume the docs are just lagging, and we should use BUILD.bazel everywhere now? Is there a link to why we should use BUILD.bazel?

[jayconrod]

We're in the process of updating our documentation (#810). We should fix this.

BUILD.bazel should be preferred for new projects. Bazel recognizes both names but prefers BUILD.bazel if both are present. The problem with BUILD is that it frequently collides with files or directories named "build" on case-insensitive file systems in projects that didn't previously use Bazel. The BUILD.bazel name was introduced about a year ago to avoid that collision.

[justinsb]

Thanks @jayconrod - that makes a lot of sense. It was also the main https://bazel.build/ site that still has a lot of BUILD references, FYI.

[ianthehat]

We have now switched to the new documentation, which I believe only uses BUILD.bazel files.
There are still some reference to BUILD files but they mean "files in the BUILD language", rather than "files named BUILD". If you find anywhere that you think is wrong now, please file a specific bug or send us a pull request to fix it.

Bazel does not take a stance on BUILD vs BUILD.bazel. We (rules_go) have chosen to strongly favor the latter because as Jay said it is far less likely to cause issues in existing repositories. This is more important for us because we are automatically generating these files.