feat: detect stardoc output change #75
Conversation
features.bzl
Outdated
| @@ -33,6 +33,11 @@ _cc = struct( | |||
| protobuf_on_allowlist = ge("8.0.0"), | |||
| ) | |||
|
|
|||
| _docs = struct( | |||
| # See https://bazelbuild.slack.com/archives/CDCMRLS23/p1727889648853179?thread_ts=1727887056.727699&cid=CDCMRLS23 | |||
There was a problem hiding this comment.
Slack links by themselves aren't great in committed code. Could you briefly describe why this is needed and also link the commit that introduced the change?
There was a problem hiding this comment.
I spent a few minutes searching the 300 or so commits since the last rolling release but couldn't find this one. @tetromino do you know offhand?
There was a problem hiding this comment.
@alexeagle - I think you're looking for bazelbuild/bazel@bd1c3af
There was a problem hiding this comment.
Thank you! Updated.
I see that https://github.com/bazelbuild/stardoc/pull/231/files is the renderer change in Stardoc that corresponds to this. I don't understand this fully - in my testing even the last rolling release of Bazel didn't print the ** on kwargs even though the commit you point out has been included since 8.0.0-pre.20240603.2.
There was a problem hiding this comment.
It looks to me as if the ** would only show up if you combine a Bazel with the linked commit and an up-to-date Stardoc.
| @@ -33,6 +33,12 @@ _cc = struct( | |||
| protobuf_on_allowlist = ge("8.0.0"), | |||
| ) | |||
|
|
|||
| _docs = struct( | |||
| # The stardoc output changed in https://github.com/bazelbuild/bazel/commit/bd1c3af2ea14e81268e940d2b8ba5ad00c3f08d7 | |||
| # This may be required for "diff tests" that assert on the generated API docs. | |||
There was a problem hiding this comment.
I don't want to make it too difficult to get a new feature in, but I wonder to what extent Stardoc guarantees output stability over time and how that aligns with major/minor releases of Bazel.
Would it make sense to only run diff tests on a single pinned Bazel version so that this kind of feature detection isn't needed? Happy to merge this if you still consider it useful.
Allows Bazel 8 upgrades in rulesets where docgen diff tests otherwise fail, for example https://github.com/aspect-build/rules_lint/pull/401/files