bug: docs should say which version each feature / function / etc. was introduced in
- Dominant language
- Java
- Stars
- 25.8k
- Forks
- 4.6k
- Avg merge
- 2d 16h
- Merged PRs (30d)
- 72
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](https://bazel.build/rules/lib/builtins/repository_ctx) 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
Research direction
Start with the repository_ctx documentation page, especially repository_ctx.getenv, and review the related discussion in issue #9016. Determine how introduction versions should be represented across functions, parameters, and behavior changes; done means the relevant Bazel documentation consistently identifies the semver version for each applicable addition or change.
Written by the indexing model from the issue text.
Assessment
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100