bazelbuild / bazelbuild/bazel

Improve clarity of error messages / docs w.r.t. "BUILD" vs "BUILD.bazel"

Open
#17,054 2 comments 0 reactions 0 assignees View on GitHub
not stale P4 team-Loading-API type: feature request
Dominant language
Java
Stars
25.8k
Forks
4.6k
Avg merge
2d 18h
Merged PRs (30d)
75

Description

Motivation is improving error messages like in #16207, so that users of repos that follow the "BUILD.bazel" convention aren't misled into thinking they need to create a file named "BUILD". (We also have the opposite problem within Google: We wouldn't necessarily want to direct users to create "BUILD.bazel" files when our monorepo exclusively uses "BUILD".)

We could pedantically mention "BUILD or BUILD.bazel" everywhere in errors an documentation, but that could get cumbersome and probably isn't worth its weight to the reader. Alternatively, we could just decide to only ever call them by one name or the other, and ensure the glossary or other concept documentation explains that this is an abbreviated form.

Contributor guide

Open the contributing guide

Research direction

Start by searching Bazel's error messages and documentation for references to BUILD and BUILD.bazel, then review the alternatives described in the issue. Done means an agreed naming convention is reflected consistently in the affected messages and concept documentation, including the distinction needed for different repository conventions.

Written by the indexing model from the issue text.

Assessment

Domain
build-system, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.