Create a tutorial to help rules authors migrate to bzlmod

[chrislovecnm]

This tutorial will focus on how to take a bazel rule set and migrate to using bzlmod. Significant differences and capabilities exist between using a WORKSPACE file and using bzlmod and MODULE.bazel.

Rough draft outline:

Introduction

• introduction to bzlmod and differences between WORKSPACE and MODULE.bazel.

Migrating to bzlmod

• bzlmod extensions
• passing values between extensions
• introduction to module_extension and tag_classes
• hub-spoke pattern
• toolchain registration
  • doing internal toolchain registrations
  • dealing with sub-modules registering toolchains
• managing rule set dependencies
• introduction to how looping through module_ctx.modules works
• cover best practices, such as putting a single module within a single bzl file.
• document how to deploy your ruleset to the bazel-central-registry
• writing examples and documentation

Complexities with bzlmod

• unsupported native calls in bzlmod - native.register_toolchains
• debugging bzlmod code by running specific targets
• folder layout differences inside of the cache
• introduction to migrating from using load statements in your WORKSPACE file to using an extension and MODULES.bzlmod.
• detecting when you are running with bzlmod vs. a WORKSPACE
• dealing with sub-modules overriding ruleset values
• Empty WORKSPACE file
• WORKSPACE.bzlmod to prevent leaking dependencies
• Why not include code in WORKSPACE.bzlmod
• use_repo names that are created and then used. How the naming creates a repo
• repo name collision with repo creation
• maintaining two different code bases for WORKSPACE and bzlmod.

@alexeagle @meteorcloudy @rickeylev - any guidance is appreciated!

[rickeylev]

Yeah, that all sounds like a good introduction to creating your own bzlmod-based project.

Something I don't see explicitly mentioned is:

1. Visibility. This is a part of bzlmod that took me awhile to get a handle on. (I'm not sure I entirely do, still 😅, but enough to understand errors enough usually)
2. Apparent vs canonical repos: when you should or shouldn't use one or the other. A common thing I saw with initial bzlmod work was trying to use canonical repo names more than necessary. Visibility issues go away once you have the canonical name, but doing that probably causes issues in some other context.
3. The upcoming isolated=True parameter of use_extension, maybe? @fmeum
4. Change in the runfiles layout

[meteorcloudy]

Thanks for creating this! /cc @Wyverald