[bazel.build] Suggestion on Target Visibility documentation improvement
- Dominant language
- Java
- Stars
- 25.8k
- Forks
- 4.6k
- Avg merge
- 2d 20h
- Merged PRs (30d)
- 72
Description
### Page link:
https://bazel.build/concepts/visibility
### Problem description (include actual vs expected text, if applicable):
When it comes to reading documentation on Bazel's visibility feature, IMHO, most devs are going to be in one of two modes: 1. Figuring out how to open up the visibility correctly 2. Setting up their project with good practice.
I think the docs could read slightly faster by having the target visibility docs suggest the better practice norm that every BUILD file declare a default visibility in the package rule at the top and override it within the lower rules, when something should be exposed. Most notable, just showing a 10 line BUILD file example with export_files, package, and a go_lib rule with a few comments about what would be visible.
As it is right now, the fact that default_visibility can be configured in the package state is within the second page of content on Target visibility, but even there the wording assumes you're versed in Bazel and know what the the package declaration is and where to find out what it's fields are so you can properly declare.
Also of note, showing devs a good simple norm on package groups would be nice as well. IMHO, the documentation is perfectly correct, but may not quickly address the most common use case of reading the documentation. It could have a "quick examples" section which assists in perpetuating the better practices without requiring devs to go to StackOverflow (which doesn't have many BUILD examples yet). Even if those quick examples pointed directly at files within GitHub.
### Where do you see this issue? (include link to specific section of the page, if applicable)
https://bazel.build/concepts/visibility
### Any other information you'd like to share?
_No response_
Contributor guide
Research direction
Start with the linked Target visibility page at https://bazel.build/concepts/visibility, especially the sections on default_visibility, package declarations, and package groups. Compare the current explanations with the requested quick-examples approach. Done means the page includes a concise BUILD example and clearer guidance on recommended visibility practices; no specific source file or test is named.
Written by the indexing model from the issue text.
Assessment
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100