bazelbuild / bazelbuild/bazel

Documentation issue: attr

Open
#13,782 1 comment 0 reactions 0 assignees View on GitHub
help wanted P3 team-Configurability team-Documentation type: documentation (cleanup)
Dominant language
Java
Stars
25.8k
Forks
4.6k
Avg merge
2d 20h
Merged PRs (30d)
72

Description

Documentation URL: https://docs.bazel.build/versions/main/skylark/lib/attr.html

The documentation for the cfg parameter is incomplete and misleading to those who have not grok-ed all of Bazel's concepts yet.

It currently states:

>
> cfg | default = None Configuration of the attribute. **It can be either "host", "exec", or "target".** This parameter is required if executable is True to guard against accidentally building host tools in the target configuration. "target" has no semantic effect, so don't set it when executable is False unless it really helps clarify your intentions.
> -- | --

If one does not navigate to the configuration link and read all of that documentation, it is unclear that you can provide your own transition. This can be problematic when first learning bazel and assuming the value can actually only be unspecified, "host", "exec", or "target".

Contributor guide

Open the contributing guide

Research direction

Start with the cfg parameter entry at the linked attr.html page, then read its configuration link to verify how custom transitions are described. Update the documentation so it explicitly states that cfg accepts user-defined transitions as well as the listed values, and confirm the explanation no longer implies the list is exhaustive.

Written by the indexing model from the issue text.

Assessment

Domain
build-system, documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.