bazelbuild / bazelbuild/bazel

[bazel.build] Suggestion on Target Visibility documentation improvement

Open
#22,332 0 comments 0 reactions 0 assignees View on GitHub
team-Documentation team-Starlark-Integration type: documentation (cleanup) untriaged
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.