bzlmod examples and documentation updates

[chrislovecnm]

Page link:

https://bazel.build/external/overview#bzlmod

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

Problem Statement

We have multiple things that have changed when using bzlmod that I have struggled to learn. Through updating and working with the rules_python examples and working on a Python tutorial, I have some experiences that I would like to share. Migration is challenging, no matter what we do. I aim to inform users why we are migrating to bzlmod and give them the documentation and example to help their journey.

Recommendations

• Improve the documentation on our primary website.
  • Improve the level of detail in the documentation and walk a user through the changes.
  • The site needs to spell out why users should do this. We plan to deprecate WORKSPACE files, and we should tell them that.
  • Document what extensions are, how to use extensions, and maybe when and how to write your extensions.
• Have each rule set have a reasonably complex example.
• Have each rule set include documentation in their README.md around bzlmod.
  • how to configure a MODULE.bzl file and the changes from using a WORKSPACE file.
  • the current support for bzlmod
• Provide documentation that links to examples and documentation in an issue or a document that helps users understand where each rule is at with bzlmod support

My experience

Here are some notes from my experience with using bzlmod.

• The syntax has changed with bzlmod. I am used to configuring a WORKSPACE file but need more documentation for the syntax used within the MODULES.bzl file.
• We have some examples using bzlmod, but the documentation within those examples is a bit light. Also, finding those examples takes a lot of work.
• The principle of what an extension is and how to use them needs to be well documented.
• We have depreciated using various parts of bazel. For instance, native.register_toolchain is no longer available.
• Certain error messages with bzlmod are misleading. For example, when you try to enable downloading of a toolchain within an extension, the error tells you to use a BUILD file.
• We need a list of where various modules are for adopting bzlmod.
• Using a WORKSPACE.bzl needs to be better documented.
• How to use other modules (sub-modules) within a mono repo needs to be better documented.
• Extensions need to be documented on how to use them. We have extensions with parameters, but we need to demonstrate how to use those parameters.

Resources

https://bazel.build/external/overview#bzlmod
bazelbuild/rules_rust#1528
https://docs.google.com/document/d/1JtXIVnXyFZ4bmbiBCr5gsTH4-opZAFf5DMMb-54kES0/edit#heading=h.5mcn15i0e1ch

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

No response

Any other information you'd like to share?

No response

[rickeylev]

FYI, a commit just went in to add a Best Practices section to the Module extensions page: https://bazel.build/external/extension#best_practices

So there's now at least a place to collect learnings about writing extensions