bazelbuild / bazelbuild/bazel

Discoverability of language-agnostic rules is poor

Open
#22,645 0 comments 0 reactions 0 assignees View on GitHub
help wanted P2 team-Documentation team-OSS type: documentation (cleanup)
Dominant language
Java
Stars
25.8k
Forks
4.6k
Avg merge
2d 18h
Merged PRs (30d)
75

Description

### Page link:

_No response_

### Problem description (include actual vs expected text, if applicable):

For a new Bazel user, it can be hard to find all the language-agnostic rules that they should leverage instead of reimplementing. Today they are split between at least three locations:

* Native rules, documented at https://bazel.build/reference/be/overview#language-agnostic-native-rules (this is good!)
* [Bazel Skylib](https://github.com/bazelbuild/bazel-skylib), which provides additional, very widely used language-agnostic rules, but is not mentioned in https://bazel.build/reference/be/overview. It's linked to from https://bazel.build/rules, but the text there makes it sound like it contains advanced utilities for rules-writers, not everyday utility rules for regular users like `copy_file` or `native_binary` ("The repository Skylib contains additional functions that can be useful when writing new rules and new macros.").
* [rules_platform](https://github.com/bazelbuild/rules_platform), which provides `platform_data`, is not even listed in https://bazel.build/rules.

### Where do you see this issue? (include link to specific section of the page, if applicable)

_No response_

### Any other information you'd like to share?

_No response_

Contributor guide

Open the contributing guide

Research direction

Start by comparing the language-agnostic native rules section at bazel.build/reference/be/overview, the bazel.build/rules page, and the linked Bazel Skylib and rules_platform repositories. Update the documentation so users can find commonly used language-agnostic rules, including Skylib and rules_platform, with descriptions that reflect their regular-user use; done means all three sources are discoverable and accurately described.

Written by the indexing model from the issue text.

Assessment

Domain
build-system, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.