bazelbuild/bazel

bug: docs should say which version each feature / function / etc. was introduced in

Open

#27470 opened on Oct 30, 2025

View on GitHub
 (2 comments) (0 reactions) (0 assignees)Java (25,384 stars) (4,465 forks)batch import
P2help wantedteam-Documentationteam-OSStype: documentation (cleanup)

Description

Page link:

No response

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

Major programming languages/platforms like node.js and python in their docs list when each function / api was introduced. This makes it far easier to use the latest docs, yet actually be targeting or at least supporting an older version of the language. Bazel should do the same: each new function, new parameter, change in behavior etc. should be documented in bazel docs with which semver version it was introduced in.

some related discussion in: https://github.com/bazelbuild/bazel/issues/9016#issuecomment-2118679907

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

I know of it most on the repository_ctx page as there were a lot of improvements / features added there over bazel 7 - I was at the time using bazel 6 and was misled by the latest docs that repository_ctx including features I couldn't actually use. In particular, repository_ctx.getenv was an api I wanted to use in bazel 6 that I discovered the hard way was not available until bazel 7.

Any other information you'd like to share?

No response

Contributor guide

Tech stack
javashell
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
mostly clear
Prerequisites
familiarity with Bazel's documentation formatknowledge of Git to check version history
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60
Research direction
Examine the existing Bazel documentation pages, especially the repository ctx page, to identify where version information is missing. Look at how the Bazel team tracks feature introductions in the codebase (e.g., release notes, git tags). Propose a systematic way to add version annotations to all function/API docs, possibly using a script or manual process. Reference the discussion in issue #9016 for additional context.