[bazel.build] Released documentation is as much as 1 year ahead of released code

[jiceatscion]

Page link:

https://bazel.build/rules/lib/builtins/repository_ctx

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

The current (i.e. default without selecting a version) documentation reflects the very head of the repository; documenting features that were committed a week ago. Per your stated release schedule, these features will not be in a release for another year. That's really not helpful to document them as current. For example I wasted time upgrading Bazel to the latest release, and then trying to figure out what I'd done wrong since the feature still appeared to not work.

I seriously would not mind browsing the documentation at HEAD and learn about features worth waiting for, but only if:

• I was informed that I'm looking at pre-release doc.
• I had clear and easy access to the same doc for the latest release. Right now only 7.0.0 is available, not 7.0.1 or 7.0.2 so, in effect, the most relevant documentation is missing (not mentioning the versioned docs aren't that obvious to get to).

Thanks all the same for sharing blaze with the world.

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

Any other information you'd like to share?

No response

[brentleyjones]

@meteorcloudy This is what we talked about in the Rules Authors SIG: the default needs to be the latest release, and we need to add HEAD to the version dropdown.

[meteorcloudy]

Sorry for the bad experience...

Last time we check, there is still some technical difficulties for changing the default doc to latest version. @fweikert can confirm if it's still true.

But I think we can at least add a banner to notify users that they are looking at the HEAD version and provide a link to versioned doc.

[jiceatscion]

Yeah, a banner would be nice.

Note that the "versioned docs" page also has a bit of a prank in it. The page has a very prominent text that tells you about the docs being at head, etc, etc. But it fails to tel you what to do to actually see the versioned docs. The most obvious thing is the "To the archives" button, which takes you to ancient stuff. Unless you raise your eyes away from the text and observe the menu bar carefully, you're not likely to notice the "Versioned docs" drop-down that just appeared. I may be oblivious but it took me three visits to that page before I noticed :-) How about having it there all the time?

[meteorcloudy]

Note that the "versioned docs" page also has a bit of a prank in it.

Indeed, I also noticed that, will fix that as well!

[Anrock]

Alright, I give up. Where is it that "Versioned docs dropdown" exactly? I've spent like an hour trying to find it but I can't. Can somebody post a screenshot with big red glowing arrow or something?

[jiceatscion]

Here you go:

[jiceatscion]

Takes me a while to find it everytime as that menu bar looks so much like it is part of the browser UI that I'm blind to it :-)

[Anrock]

Hm, for me it's just a button

that leads to this page https://bazel.build/versions that basically tells me to use dropdown.

P.S. Alright, I resized my browser window so "versioned docs" didn't overflow under "more" and when it's not overflowed it actually has a dropdown. That's a bug.

[meteorcloudy]

Thanks to @fmeum, we have landed #22725

Now you can switch between versions using:

[meteorcloudy]

I'll close this for now.

[Anrock]

@meteorcloudy pressing 6.5 or 6.4 there leads to 404 page

[meteorcloudy]

That is because the doc was restructured between 7.x and 6.x, so not every page has an older version. For 6.x, please start from https://bazel.build/versions/6.4.0/rules/lib/globals