feat: support bzlmod snippets in bzlrelease (#270)

- Introduce `geneate_module_snippet`.
- Update `generate_release_notes` and `update_readme` to use
`generate_module_snippet`.
- Add module snippet section to `README.md`.

Closes #269.

README.md

@@ -33,6 +33,15 @@ more information on how to use the projects from this repository in your workspa
 how-to links above and review the [the generated documentation](/doc/).
 
 
+### `MODULE.bazel` Snippet
+
+<!-- BEGIN MODULE SNIPPET -->
+```python
+bazel_dep(name = "cgrindel_bazel_starlib", version = "0.14.9")
+```
+<!-- END MODULE SNIPPET -->
+
+
 ### Workspace Configuration
 
 <!-- BEGIN WORKSPACE SNIPPET -->

bzlrelease/BUILD.bazel

@@ -16,6 +16,7 @@ bzl_library(
     srcs = ["defs.bzl"],
     deps = [
         "//bzlrelease/private:create_release",
+        "//bzlrelease/private:generate_module_snippet",
         "//bzlrelease/private:generate_release_notes",
         "//bzlrelease/private:generate_workspace_snippet",
         "//bzlrelease/private:hash_sha256",

bzlrelease/defs.bzl

@@ -4,6 +4,10 @@ load(
     "//bzlrelease/private:create_release.bzl",
     _create_release = "create_release",
 )
+load(
+    "//bzlrelease/private:generate_module_snippet.bzl",
+    _generate_module_snippet = "generate_module_snippet",
+)
 load(
     "//bzlrelease/private:generate_release_notes.bzl",
     _generate_release_notes = "generate_release_notes",
@@ -23,13 +27,9 @@ load(
 )
 
 create_release = _create_release
-
-generate_workspace_snippet = _generate_workspace_snippet
-
+generate_module_snippet = _generate_module_snippet
 generate_release_notes = _generate_release_notes
-
+generate_workspace_snippet = _generate_workspace_snippet
 hash_sha256 = _hash_sha256
-
-update_readme = _update_readme
-
 release_archive = _release_archive
+update_readme = _update_readme

bzlrelease/private/BUILD.bazel

@@ -5,6 +5,14 @@ package(default_visibility = ["//bzlrelease:__subpackages__"])
 
 bzlformat_pkg(name = "bzlformat")
 
+bzl_library(
+    name = "generate_module_snippet",
+    srcs = ["generate_module_snippet.bzl"],
+    deps = [
+        "//shlib/rules:execute_binary",
+    ],
+)
+
 bzl_library(
     name = "generate_workspace_snippet",
     srcs = ["generate_workspace_snippet.bzl"],

bzlrelease/private/generate_module_snippet.bzl

@@ -0,0 +1,19 @@
+"""Macro that defines a target that generates a Bazel module snippet."""
+
+load("//shlib/rules:execute_binary.bzl", "execute_binary")
+
+def generate_module_snippet(name, module_name):
+    """Generate Bazel module snippet.
+
+    Args:
+        name: The name of the target as a `string`.
+        module_name: The name of the Bazel module as a `string`.
+
+    Returns:
+    """
+    arguments = ["--module_name", module_name]
+    execute_binary(
+        name = name,
+        arguments = arguments,
+        binary = "@cgrindel_bazel_starlib//bzlrelease/tools:generate_module_snippet",
+    )

bzlrelease/private/generate_release_notes.bzl

@@ -2,7 +2,10 @@
 
 load("//shlib/rules:execute_binary.bzl", "execute_binary", "file_placeholder")
 
-def generate_release_notes(name, generate_workspace_snippet):
+def generate_release_notes(
+        name,
+        generate_workspace_snippet = None,
+        generate_module_snippet = None):
     """Defines an executable target that generates release notes as Github markdown.
 
     Typically, this macro is used in conjunction with the \
@@ -12,15 +15,22 @@ def generate_release_notes(name, generate_workspace_snippet):
 
     Args:
         name: The name of the executable target as a `string`.
-        generate_workspace_snippet: The label that should be executed to
-                                    generate the workspace snippet.
+        generate_workspace_snippet: Optional.The label that should be executed to
+            generate the workspace snippet.
+        generate_module_snippet: Optional.The label that should be executed to
+            generate the Bazel module snippet.
     """
     file_arguments = {}
     arguments = []
 
-    file_key = "generate_workspace_snippet"
-    arguments.extend(["--generate_workspace_snippet", file_placeholder(file_key)])
-    file_arguments[generate_workspace_snippet] = file_key
+    if generate_workspace_snippet != None:
+        file_key = "generate_workspace_snippet"
+        arguments.extend(["--generate_workspace_snippet", file_placeholder(file_key)])
+        file_arguments[generate_workspace_snippet] = file_key
+    if generate_module_snippet != None:
+        file_key = "generate_module_snippet"
+        arguments.extend(["--generate_module_snippet", file_placeholder(file_key)])
+        file_arguments[generate_module_snippet] = file_key
 
     execute_binary(
         name = name,

bzlrelease/private/update_readme.bzl

@@ -2,7 +2,11 @@
 
 load("//shlib/rules:execute_binary.bzl", "execute_binary", "file_placeholder")
 
-def update_readme(name, generate_workspace_snippet, readme = None):
+def update_readme(
+        name,
+        generate_workspace_snippet = None,
+        generate_module_snippet = None,
+        readme = None):
     """Declares an executable target that updates a README.md with an updated workspace snippet.
 
     The utility will replace the lines between `<!-- BEGIN WORKSPACE SNIPPET -->` and \
@@ -11,18 +15,24 @@ def update_readme(name, generate_workspace_snippet, readme = None):
 
     Args:
         name: The name of the executable target as a `string`.
-        generate_workspace_snippet: The label that should be executed to
-                                    generate the workspace snippet.
+        generate_workspace_snippet: Optional. The label that should be executed to
+            generate the workspace snippet.
+        generate_module_snippet: Optional. The label that should be executed to
+            generate the Bazel module snippet.
         readme: A `string` representing the relative path to the README.md
-                file from the root of the workspace.
+            file from the root of the workspace.
     """
     file_arguments = {}
     arguments = []
 
-    file_key = "generate_workspace_snippet"
-    arguments.extend(["--generate_workspace_snippet", file_placeholder(file_key)])
-    file_arguments[generate_workspace_snippet] = file_key
-
+    if generate_workspace_snippet != None:
+        file_key = "generate_workspace_snippet"
+        arguments.extend(["--generate_workspace_snippet", file_placeholder(file_key)])
+        file_arguments[generate_workspace_snippet] = file_key
+    if generate_module_snippet != None:
+        file_key = "generate_module_snippet"
+        arguments.extend(["--generate_module_snippet", file_placeholder(file_key)])
+        file_arguments[generate_module_snippet] = file_key
     if readme != None:
         arguments.extend(["--readme", readme])
 

bzlrelease/tools/BUILD.bazel

@@ -107,6 +107,16 @@ sh_binary(
     ],
 )
 
+sh_binary(
+    name = "generate_module_snippet",
+    srcs = ["generate_module_snippet.sh"],
+    visibility = ["//visibility:public"],
+    deps = [
+        "//shlib/lib:fail",
+        "@bazel_tools//tools/bash/runfiles",
+    ],
+)
+
 # MARK: - Collect Files for Integation Tests
 
 filegroup(

tests/bzlrelease_tests/tools_tests/generate_fake_snippet.sh → bzlrelease/tools/generate_module_snippet.sh

@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 
+# Generates a Bazel module snippet suitable for inclusion in a MODULE.bazel 
+# file.
+
 # --- begin runfiles.bash initialization v3 ---
 # Copy-pasted from the Bazel Bash runfiles library v3.
 set -uo pipefail; set +e; f=bazel_tools/tools/bash/runfiles/runfiles.bash
@@ -11,14 +14,26 @@ source "${RUNFILES_DIR:-/dev/null}/$f" 2>/dev/null || \
   { echo>&2 "ERROR: cannot find $f"; exit 1; }; f=; set -e
 # --- end runfiles.bash initialization v3 ---
 
+# MARK - Locate Dependencies
+
 fail_sh_location=cgrindel_bazel_starlib/shlib/lib/fail.sh
 fail_sh="$(rlocation "${fail_sh_location}")" || \
   (echo >&2 "Failed to locate ${fail_sh_location}" && exit 1)
 source "${fail_sh}"
 
+# MARK - Process Args
+
 args=()
 while (("$#")); do
   case "${1}" in
+    "--module_name")
+      module_name="${2}"
+      shift 2
+      ;;
+    "--version")
+      version="${2}"
+      shift 2
+      ;;
     "--output")
       output_path="${2}"
       shift 2
@@ -30,11 +45,36 @@ while (("$#")); do
   esac
 done
 
-[[ -z "${output_path:-}" ]] && fail "Expected an output path."
+if [[ -z "${module_name:-}" ]]; then
+  fail "A module name must be specified."
+fi
+
+if [[ -z "${version:-}" ]]; then
+  fail "A version must be specified."
+fi
+if [[ "${version}" =~ ^v ]]; then
+  version="${version:1}"
+fi
+
+# MARK - Generate the Snippet
+
+snippet="$(cat <<-EOF
+bazel_dep(name = "${module_name}", version = "${version}")
+EOF
+)"
 
-echo "
-This is the beginning of the fake snippet.
+snippet="$(cat <<-EOF
+\`\`\`python
+${snippet}
+\`\`\`
+EOF
+)"
 
+# MARK - Output the Snippet
 
-This is the end of the fake snippet.
-" > "${output_path}"
+# Output the snippet
+if [[ -z "${output_path:-}" ]]; then
+  echo "${snippet}"
+else
+  echo "${snippet}" > "${output_path}"
+fi

bzlrelease/tools/generate_release_notes.sh

@@ -42,6 +42,15 @@ while (("$#")); do
         generate_workspace_snippet="${starting_dir}/${generate_workspace_snippet}"
       shift 2
       ;;
+    "--generate_module_snippet")
+      # If the input path is not absolute, then resolve it to be relative to
+      # the starting directory. We do this before we starting changing
+      # directories.
+      generate_module_snippet="${2}"
+      [[ "${generate_module_snippet}" =~ ^/ ]] || \
+        generate_module_snippet="${starting_dir}/${generate_module_snippet}"
+      shift 2
+      ;;
     --*)
       fail "Unrecognized flag ${1}."
       ;;
@@ -55,9 +64,9 @@ done
 [[ ${#args[@]} == 0 ]] && fail "A tag name for the release must be specified."
 tag_name="${args[0]}"
 
-[[ -z "${generate_workspace_snippet:-}" ]] && \
-  fail "Expected a value for --generate_workspace_snippet."
-
+if [[ -z "${generate_workspace_snippet:-}" ]] && [[ -z "${generate_module_snippet:-}" ]]; then
+  fail "Expect at least one of the following flags to be specified: --generate_workspace_snippet, --generate_module_snippet."
+fi
 
 # MARK - Generate the changelog.
 
@@ -71,16 +80,40 @@ cd "${BUILD_WORKSPACE_DIRECTORY}"
 
 changelog_md="$( "${generate_gh_changelog_sh}" "${tag_name}" )"
 
-workspace_snippet="$( "${generate_workspace_snippet}" --tag "${tag_name}" )"
+if [[ -n "${generate_workspace_snippet:-}" ]]; then
+  workspace_snippet="$( "${generate_workspace_snippet}" --tag "${tag_name}" )"
+fi
+
+if [[ -n "${generate_module_snippet:-}" ]]; then
+  module_snippet="$( "${generate_module_snippet}" --version "${tag_name}" )"
+fi
 
 release_notes_md="$(cat <<-EOF
 ${changelog_md}
+EOF
+)"
+
+if [[ -n "${module_snippet:-}" ]]; then
+  release_notes_md="$(cat <<-EOF
+${release_notes_md}
+
+## Bazel Module Snippet
+
+${module_snippet}
+EOF
+)"
+fi
+
+if [[ -n "${workspace_snippet:-}" ]]; then
+  release_notes_md="$(cat <<-EOF
+${release_notes_md}
 
 ## Workspace Snippet
 
 ${workspace_snippet}
 EOF
 )"
+fi
 
 # Output the changelog
 if [[ -z "${output_path:-}" ]]; then