Skip to content

doc: add "best practices" for module version and compatibility_level #26356

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed

Conversation

jjmaestro
Copy link
Contributor

While asking about best practices regarding releasing Bazel modules in Slack, I learned a few things that I would have loved to see in the Bazel docs (e.g. leaving the version unset or set to the default "" value can prevent issues like bazel-contrib/rules_go#4380 when the module is used via non-registry overrides).

For more info, see bazel-contrib/rules-template/pull/148 and this Slack thread:
https://bazelbuild.slack.com/archives/CA31HN1T3/p1750406404452179

@github-actions github-actions bot added team-Documentation Documentation improvements that cannot be directly linked to other team labels awaiting-review PR is awaiting review from an assigned reviewer labels Jun 22, 2025
@jjmaestro
Copy link
Contributor Author

jjmaestro commented Jun 22, 2025

CC @fmeum & @Wyverald, let me know if these docs are OK and please feel free to suggest edits, improvements, etc, as I might have gotten some things wrong. Thanks!!

Copy link
Member

@Wyverald Wyverald left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks for the writeup. I found it quite enlightening, myself :)

I do wonder whether this new content belongs on this page, since this is quite in-depth stuff that goes beyond the introduction of basic concepts (such as the version format, how selection works, etc). Although I don't immediately have a better idea where to put it either (maybe in the rules template itself, or maybe in faq.md?) WDYT?

@jjmaestro
Copy link
Contributor Author

thanks for the writeup. I found it quite enlightening, myself :)

thanks! :)

I do wonder whether this new content belongs on this page, since this is quite in-depth stuff that goes beyond the introduction of basic concepts (such as the version format, how selection works, etc). Although I don't immediately have a better idea where to put it either (maybe in the rules template itself, or maybe in faq.md?) WDYT?

I'm happy to move this to wherever any of you see fit, but I really think this is the best place for this stuff. These were the docs I read before asking in Slack... basically, I went through the steps I mentioned and I didn't find the answers I was looking for. I think it has all the context required to understand the issues that arise from setting the version in the source MODULE.bazel (except the registry stuff, which I've linked and linked back from the registry page).

The way I see it, if you land in this page, either you are coming from the MODULE.bazel docs (from the "See the documentation" links in module), or you've been going through the Bazel docs, in which case you should have been reading through Bazel > User Guide > Basics, then "Getting started with BUILD files" and "Running Bazel", and finally "External dependencies" Overview.

Either way, this is the page that discusses most of the important stuff about the external dependencies and, tbh, most of the concepts in this page are quite complex and in-depth already 😅 so I think it's quite fitting!

I think rules-template or a separate FAQ would be more removed from context. And I've already added comments to the rules-template MODULE.bazel, I was actually hoping to get this landed and to update those comments with a link :)

Happy to hear more reviewers / ideas, and as I said, I'll move it to wherever you think is best.

Thanks!

@jjmaestro
Copy link
Contributor Author

@Wyverald I've given it more thought and I've moved it to FAQ, I think you are right, it can also fit in there and this way the "Bazel modules" page won't be more / so overwhelming 😅 .

Let me know what you think!

@jjmaestro jjmaestro force-pushed the docs-module-best-practices branch from 86d88d5 to 8546b0d Compare June 24, 2025 12:51
@iancha1992 iancha1992 added the team-OSS Issues for the Bazel OSS team: installation, release processBazel packaging, website label Jun 24, 2025
While asking about best practices regarding releasing Bazel modules in
Slack, I learned a few things that I would have loved to see in the
Bazel docs (e.g. leaving the version unset or set to the default ""
value can prevent issues like bazel-contrib/rules_go#4380 when the
module is used via non-registry overrides).

For more info, see bazel-contrib/rules-template/pull/148 and this Slack
thread:
https://bazelbuild.slack.com/archives/CA31HN1T3/p1750406404452179
@jjmaestro jjmaestro force-pushed the docs-module-best-practices branch from 8546b0d to 3b662fa Compare June 25, 2025 20:31
@jjmaestro
Copy link
Contributor Author

@Wyverald could you check the changes and see if the new version in FAQ is better? 🙏 Thanks!

@Wyverald Wyverald added awaiting-PR-merge PR has been approved by a reviewer and is ready to be merge internally and removed awaiting-review PR is awaiting review from an assigned reviewer labels Jun 27, 2025
@copybara-service copybara-service bot closed this in 1458455 Jul 1, 2025
@github-actions github-actions bot removed the awaiting-PR-merge PR has been approved by a reviewer and is ready to be merge internally label Jul 1, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
team-Documentation Documentation improvements that cannot be directly linked to other team labels team-OSS Issues for the Bazel OSS team: installation, release processBazel packaging, website
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants