From fb0b4233626e43a6e3e185060240068fc17183bd Mon Sep 17 00:00:00 2001 From: Chuck Grindel Date: Thu, 30 Dec 2021 12:00:57 -0700 Subject: [PATCH] Organized release-related code under `bzlrelease` (#45) Moved release-related macros under bzlrelease. Migrated code from cgrindel/bazel-doc to this repo. It now lives under bazeldoc. This migration was planned. It happened now so that a change to doc_for_provs could be added to support documentation in different directories. Added release package and moved this repository's release declarations there. Also, moved the snippets template. --- BUILD.bazel | 29 +---- README.md | 4 + WORKSPACE | 10 -- bazeldoc/BUILD.bazel | 17 +++ bazeldoc/defs.bzl | 12 ++ bazeldoc/private/BUILD.bazel | 76 ++++++++++++ bazeldoc/private/diff_test_for_provs.bzl | 33 ++++++ bazeldoc/private/doc_for_provs.bzl | 17 +++ bazeldoc/private/doc_utilities.bzl | 32 +++++ bazeldoc/private/providers.bzl | 66 +++++++++++ bazeldoc/private/stardoc_for_prov.bzl | 37 ++++++ bazeldoc/private/update_doc.bzl | 38 ++++++ bazeldoc/private/write_doc.bzl | 26 ++++ bazeldoc/private/write_file_list.bzl | 48 ++++++++ bazeldoc/private/write_header.bzl | 45 +++++++ bzlrelease/BUILD.bazel | 18 +++ bzlrelease/defs.bzl | 27 +++++ bzlrelease/private/BUILD.bazel | 43 +++++++ bzlrelease/private/create_release.bzl | 20 ++++ .../private/generate_release_notes.bzl | 0 .../private/generate_workspace_snippet.bzl | 0 {rules => bzlrelease}/private/hash_sha256.bzl | 0 .../private/update_readme.bzl | 0 deps.bzl | 26 ++-- doc/BUILD.bazel | 6 +- doc/README.md | 10 +- doc/bazeldoc/BUILD.bazel | 106 +++++++++++++++++ doc/bazeldoc/README.md | 4 + doc/bazeldoc/api.md | 9 ++ doc/bazeldoc/build_rules_overview.md | 89 ++++++++++++++ doc/bazeldoc/providers.md | 36 ++++++ doc/bzlrelease/BUILD.bazel | 112 ++++++++++++++++++ doc/bzlrelease/README.md | 4 + doc/bzlrelease/api.md | 6 + doc/bzlrelease/create_release.md | 26 ++++ .../generate_release_notes.md | 0 .../generate_workspace_snippet.md | 0 doc/{ => bzlrelease}/hash_sha256.md | 0 doc/bzlrelease/rules.md | 11 ++ doc/{ => bzlrelease}/update_readme.md | 0 doc/rules.md | 4 - release/BUILD.bazel | 33 ++++++ release/README.md | 3 + .../workspace_snippet.tmpl | 4 - rules/BUILD.bazel | 32 ----- rules/generate_release_notes.bzl | 6 - rules/generate_workspace_snippet.bzl | 6 - rules/hash_sha256.bzl | 3 - rules/private/BUILD.bazel | 29 ----- rules/update_readme.bzl | 6 - .../generate_release_notes_tests/BUILD.bazel | 3 +- .../generate_release_notes_test.sh | 2 +- .../workspace_snippet.tmpl | 4 - .../BUILD.bazel | 2 +- .../generate_workspace_snippet_test.sh | 4 +- .../workspace_snippet.tmpl | 4 - .../rules_tests/hash_sha256_tests/BUILD.bazel | 2 +- .../rules_tests/hash_sha256_tests/data.txt | 0 .../hash_sha256_tests/hash_sha256_test.sh | 0 .../update_readme_tests/BUILD.bazel | 3 +- .../update_readme_tests/update_readme_test.sh | 2 +- .../workspace_snippet.tmpl | 4 - tests/tools_tests/workspace_snippet.tmpl | 4 - tools/create_release.sh | 29 ++++- 64 files changed, 1055 insertions(+), 177 deletions(-) create mode 100644 bazeldoc/BUILD.bazel create mode 100644 bazeldoc/defs.bzl create mode 100644 bazeldoc/private/BUILD.bazel create mode 100644 bazeldoc/private/diff_test_for_provs.bzl create mode 100644 bazeldoc/private/doc_for_provs.bzl create mode 100644 bazeldoc/private/doc_utilities.bzl create mode 100644 bazeldoc/private/providers.bzl create mode 100644 bazeldoc/private/stardoc_for_prov.bzl create mode 100644 bazeldoc/private/update_doc.bzl create mode 100644 bazeldoc/private/write_doc.bzl create mode 100644 bazeldoc/private/write_file_list.bzl create mode 100644 bazeldoc/private/write_header.bzl create mode 100644 bzlrelease/BUILD.bazel create mode 100644 bzlrelease/defs.bzl create mode 100644 bzlrelease/private/BUILD.bazel create mode 100644 bzlrelease/private/create_release.bzl rename {rules => bzlrelease}/private/generate_release_notes.bzl (100%) rename {rules => bzlrelease}/private/generate_workspace_snippet.bzl (100%) rename {rules => bzlrelease}/private/hash_sha256.bzl (100%) rename {rules => bzlrelease}/private/update_readme.bzl (100%) create mode 100644 doc/bazeldoc/BUILD.bazel create mode 100644 doc/bazeldoc/README.md create mode 100755 doc/bazeldoc/api.md create mode 100755 doc/bazeldoc/build_rules_overview.md create mode 100755 doc/bazeldoc/providers.md create mode 100644 doc/bzlrelease/BUILD.bazel create mode 100644 doc/bzlrelease/README.md create mode 100755 doc/bzlrelease/api.md create mode 100755 doc/bzlrelease/create_release.md rename doc/{ => bzlrelease}/generate_release_notes.md (100%) rename doc/{ => bzlrelease}/generate_workspace_snippet.md (100%) rename doc/{ => bzlrelease}/hash_sha256.md (100%) create mode 100755 doc/bzlrelease/rules.md rename doc/{ => bzlrelease}/update_readme.md (100%) create mode 100644 release/BUILD.bazel create mode 100644 release/README.md rename {tests/rules_tests/generate_release_notes_tests => release}/workspace_snippet.tmpl (79%) delete mode 100644 rules/generate_release_notes.bzl delete mode 100644 rules/generate_workspace_snippet.bzl delete mode 100644 rules/hash_sha256.bzl delete mode 100644 rules/update_readme.bzl rename tests/{ => bzlrelease_tests}/rules_tests/generate_release_notes_tests/BUILD.bazel (87%) rename tests/{ => bzlrelease_tests}/rules_tests/generate_release_notes_tests/generate_release_notes_test.sh (94%) rename tests/{rules_tests/generate_workspace_snippet_tests => bzlrelease_tests/rules_tests/generate_release_notes_tests}/workspace_snippet.tmpl (79%) rename tests/{ => bzlrelease_tests}/rules_tests/generate_workspace_snippet_tests/BUILD.bazel (92%) rename tests/{ => bzlrelease_tests}/rules_tests/generate_workspace_snippet_tests/generate_workspace_snippet_test.sh (88%) rename tests/{rules_tests/update_readme_tests => bzlrelease_tests/rules_tests/generate_workspace_snippet_tests}/workspace_snippet.tmpl (79%) rename tests/{ => bzlrelease_tests}/rules_tests/hash_sha256_tests/BUILD.bazel (95%) rename tests/{ => bzlrelease_tests}/rules_tests/hash_sha256_tests/data.txt (100%) rename tests/{ => bzlrelease_tests}/rules_tests/hash_sha256_tests/hash_sha256_test.sh (100%) rename tests/{ => bzlrelease_tests}/rules_tests/update_readme_tests/BUILD.bazel (88%) rename tests/{ => bzlrelease_tests}/rules_tests/update_readme_tests/update_readme_test.sh (95%) rename workspace_snippet.tmpl => tests/bzlrelease_tests/rules_tests/update_readme_tests/workspace_snippet.tmpl (79%) diff --git a/BUILD.bazel b/BUILD.bazel index 08b83568..f88f99d3 100644 --- a/BUILD.bazel +++ b/BUILD.bazel @@ -7,10 +7,6 @@ load( "@cgrindel_rules_updatesrc//updatesrc:updatesrc.bzl", "updatesrc_update_all", ) -load("@rules_pkg//:pkg.bzl", "pkg_tar") -load("//rules:generate_release_notes.bzl", "generate_release_notes") -load("//rules:generate_workspace_snippet.bzl", "generate_workspace_snippet") -load("//rules:update_readme.bzl", "update_readme") bzlformat_pkg(name = "bzlformat") @@ -21,6 +17,8 @@ bzlformat_missing_pkgs( updatesrc_update_all( name = "update_all", targets_to_run = [ + "//doc/bazeldoc:update", + "//doc/bzlrelease:update", "//doc:update", ":bzlformat_missing_pkgs_fix", ], @@ -35,29 +33,12 @@ test_suite( "manual", ], tests = [ + "//tests/bzlrelease_tests/rules_tests/generate_release_notes_tests:integration_tests", + "//tests/bzlrelease_tests/rules_tests/generate_workspace_snippet_tests:integration_tests", + "//tests/bzlrelease_tests/rules_tests/update_readme_tests:integration_tests", "//tests/lib_tests/private_tests/git_tests:integration_tests", "//tests/lib_tests/private_tests/github_tests:integration_tests", - "//tests/rules_tests/generate_release_notes_tests:integration_tests", - "//tests/rules_tests/generate_workspace_snippet_tests:integration_tests", - "//tests/rules_tests/update_readme_tests:integration_tests", "//tests/tools_tests:integration_tests", ], visibility = ["//:__subpackages__"], ) - -# MARK: - Release - -generate_workspace_snippet( - name = "generate_workspace_snippet", - template = "workspace_snippet.tmpl", -) - -generate_release_notes( - name = "generate_release_notes", - generate_workspace_snippet = ":generate_workspace_snippet", -) - -update_readme( - name = "update_readme", - generate_workspace_snippet = ":generate_workspace_snippet", -) diff --git a/README.md b/README.md index 011cb0cc..0b0000f0 100644 --- a/README.md +++ b/README.md @@ -40,3 +40,7 @@ load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories") stardoc_repositories() ``` + +## Other Documentation + +- [Release Process](release/README.md) diff --git a/WORKSPACE b/WORKSPACE index 827829ae..8f199097 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -8,10 +8,6 @@ load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace") bazel_skylib_workspace() -load("@cgrindel_bazel_doc//bazeldoc:deps.bzl", "bazeldoc_dependencies") - -bazeldoc_dependencies() - load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories") stardoc_repositories() @@ -40,9 +36,3 @@ gazelle_dependencies() load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps") protobuf_deps() - -# MARK: - Release Deps - -load("@rules_pkg//:deps.bzl", "rules_pkg_dependencies") - -rules_pkg_dependencies() diff --git a/bazeldoc/BUILD.bazel b/bazeldoc/BUILD.bazel new file mode 100644 index 00000000..864e696c --- /dev/null +++ b/bazeldoc/BUILD.bazel @@ -0,0 +1,17 @@ +load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg") +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + +package(default_visibility = ["//visibility:public"]) + +bzlformat_pkg(name = "bzlformat") + +bzl_library( + name = "defs", + srcs = ["defs.bzl"], + deps = [ + "//bazeldoc/private:doc_for_provs", + "//bazeldoc/private:providers", + "//bazeldoc/private:write_file_list", + "//bazeldoc/private:write_header", + ], +) diff --git a/bazeldoc/defs.bzl b/bazeldoc/defs.bzl new file mode 100644 index 00000000..6ae9d79c --- /dev/null +++ b/bazeldoc/defs.bzl @@ -0,0 +1,12 @@ +load("//bazeldoc/private:doc_for_provs.bzl", _doc_for_provs = "doc_for_provs") +load("//bazeldoc/private:write_header.bzl", _write_header = "write_header") +load("//bazeldoc/private:providers.bzl", _providers = "providers") +load("//bazeldoc/private:write_file_list.bzl", _write_file_list = "write_file_list") + +# Rules and Macros +doc_for_provs = _doc_for_provs +write_header = _write_header +write_file_list = _write_file_list + +# API +providers = _providers diff --git a/bazeldoc/private/BUILD.bazel b/bazeldoc/private/BUILD.bazel new file mode 100644 index 00000000..61aaf018 --- /dev/null +++ b/bazeldoc/private/BUILD.bazel @@ -0,0 +1,76 @@ +load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg") +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + +package(default_visibility = ["//bazeldoc:__subpackages__"]) + +bzlformat_pkg(name = "bzlformat") + +bzl_library( + name = "diff_test_for_provs", + srcs = ["diff_test_for_provs.bzl"], + deps = [ + "@bazel_skylib//rules:diff_test", + ], +) + +bzl_library( + name = "doc_for_provs", + srcs = ["doc_for_provs.bzl"], + deps = [ + ":diff_test_for_provs", + ":stardoc_for_prov", + ":update_doc", + ], +) + +bzl_library( + name = "doc_utilities", + srcs = ["doc_utilities.bzl"], +) + +bzl_library( + name = "providers", + srcs = ["providers.bzl"], +) + +bzl_library( + name = "stardoc_for_prov", + srcs = ["stardoc_for_prov.bzl"], + deps = [ + "@io_bazel_stardoc//stardoc:stardoc_lib", + ], +) + +bzl_library( + name = "update_doc", + srcs = ["update_doc.bzl"], + deps = [ + "@bazel_skylib//rules:write_file", + ], +) + +bzl_library( + name = "write_doc", + srcs = ["write_doc.bzl"], + deps = [ + "@bazel_skylib//rules:write_file", + ], +) + +bzl_library( + name = "write_file_list", + srcs = ["write_file_list.bzl"], + deps = [ + ":doc_utilities", + ":write_doc", + ], +) + +bzl_library( + name = "write_header", + srcs = ["write_header.bzl"], + deps = [ + ":doc_utilities", + ":write_doc", + ], +) diff --git a/bazeldoc/private/diff_test_for_provs.bzl b/bazeldoc/private/diff_test_for_provs.bzl new file mode 100644 index 00000000..7041a80e --- /dev/null +++ b/bazeldoc/private/diff_test_for_provs.bzl @@ -0,0 +1,33 @@ +load("@bazel_skylib//rules:diff_test.bzl", "diff_test") + +def diff_test_for_prov(doc_prov): + """Defines a `diff_test` for a document provider. + + Args: + doc_prov: A `struct` as returned from `providers.create()`. + + Returns: + None. + """ + diff_test( + name = "test_" + doc_prov.name, + file1 = doc_prov.out_basename, + file2 = doc_prov.doc_basename, + ) + +def diff_test_for_provs(doc_provs): + """Defines a `diff_test` for each of the provided document providers. + + Args: + doc_provs: A `list` of document provider `struct` values as returned + from `providers.create()`. + + Returns: + None. + """ + [ + diff_test_for_prov( + doc_prov = doc_prov, + ) + for doc_prov in doc_provs + ] diff --git a/bazeldoc/private/doc_for_provs.bzl b/bazeldoc/private/doc_for_provs.bzl new file mode 100644 index 00000000..fd15c234 --- /dev/null +++ b/bazeldoc/private/doc_for_provs.bzl @@ -0,0 +1,17 @@ +load(":stardoc_for_prov.bzl", "stardoc_for_provs") +load(":diff_test_for_provs.bzl", "diff_test_for_provs") +load(":update_doc.bzl", "update_doc") + +def doc_for_provs(doc_provs, doc_path = "doc"): + """Defines targets for generating documentation, testing that the generated doc matches the workspace directory, and copying the generated doc to the workspace directory. + + Args: + doc_provs: A `list` of document provider `struct` values as returned + from `providers.create()`. + + Returns: + None. + """ + stardoc_for_provs(doc_provs = doc_provs) + diff_test_for_provs(doc_provs = doc_provs) + update_doc(doc_provs = doc_provs, doc_path = doc_path) diff --git a/bazeldoc/private/doc_utilities.bzl b/bazeldoc/private/doc_utilities.bzl new file mode 100644 index 00000000..16e5664d --- /dev/null +++ b/bazeldoc/private/doc_utilities.bzl @@ -0,0 +1,32 @@ +"""Defines utility functions for working with markdown documentation files.""" + +def _link(label, url): + """Creates a markdown link. + + Args: + label: The label for the link as a `string`. + url: The URL for the link as a `string`. + + Returns: + A markdown link as a `string`. + """ + return "[{label}]({url})".format( + label = label, + url = url, + ) + +def _toc_entry(label, url): + """Creates table-of-contents (TOC) entry suitable for markdown documents. + + Args: + label: The label for the link as a `string`. + url: The URL for the link as a `string`. + + Returns: + """ + return " * " + _link(label, url) + +doc_utilities = struct( + link = _link, + toc_entry = _toc_entry, +) diff --git a/bazeldoc/private/providers.bzl b/bazeldoc/private/providers.bzl new file mode 100644 index 00000000..9a83ee98 --- /dev/null +++ b/bazeldoc/private/providers.bzl @@ -0,0 +1,66 @@ +"""Defines functions for creating document provider `struct` values.""" + +def _create( + name, + stardoc_input, + deps, + doc_label = None, + out_basename = None, + doc_basename = None, + header_label = None, + header_basename = None, + symbols = None, + is_stardoc = True): + """Create a documentation provider. + + Args: + name: A `string` which identifies the doc output. If no `symbols` + are provided, all of the symbols which are defined in the + corresponding `.bzl` file are documented. + stardoc_input: A `string` representing the input label provided to the + `stardoc` declaration. + deps: A `list` of deps for the stardoc rule. + doc_label: Optional. A `string` which is the doc label name. + out_basename: Optional. A `string` which is the basename for the + output file. + doc_basename: Optional. A `string` which is the basename for the + final documentation file. + header_label: Optional. A `string` which is the header label name, + if the header is being generated. + header_basename: Optional. The basename (`string`) of the header + filename file, if one is being used. + symbols: Optional. A `list` of symbol names that should be included + in the documentation. + is_stardoc: A `bool` indicating whether a `stardoc` declaration should + be created. + + Returns: + A `struct` representing a documentation provider. + """ + if doc_label == None: + doc_label = name + "_doc" + if out_basename == None: + out_basename = name + ".md_" + if doc_basename == None: + doc_basename = name + ".md" + if header_label == None: + header_label = name + "_header" + if header_basename == None: + header_basename = header_label + ".vm" + + return struct( + name = name, + stardoc_input = stardoc_input, + deps = deps, + doc_label = doc_label, + out_basename = out_basename, + doc_basename = doc_basename, + header_label = header_label, + header_basename = header_basename, + symbols = symbols, + is_stardoc = is_stardoc, + ) + +providers = struct( + create = _create, +) diff --git a/bazeldoc/private/stardoc_for_prov.bzl b/bazeldoc/private/stardoc_for_prov.bzl new file mode 100644 index 00000000..18509a80 --- /dev/null +++ b/bazeldoc/private/stardoc_for_prov.bzl @@ -0,0 +1,37 @@ +load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") + +def stardoc_for_prov(doc_prov): + """Defines a `stardoc` target for a document provider. + + Args: + doc_prov: A `struct` as returned from `providers.create()`. + + Returns: + None. + """ + stardoc( + name = doc_prov.name, + out = doc_prov.out_basename, + header_template = doc_prov.header_basename, + input = doc_prov.stardoc_input, + symbol_names = doc_prov.symbols, + deps = doc_prov.deps, + ) + +def stardoc_for_provs(doc_provs): + """Defines a `stardoc` for each of the provided document providers. + + Args: + doc_provs: A `list` of document provider `struct` values as returned + from `providers.create()`. + + Returns: + None. + """ + [ + stardoc_for_prov( + doc_prov = doc_prov, + ) + for doc_prov in doc_provs + if doc_prov.is_stardoc + ] diff --git a/bazeldoc/private/update_doc.bzl b/bazeldoc/private/update_doc.bzl new file mode 100644 index 00000000..f13aca68 --- /dev/null +++ b/bazeldoc/private/update_doc.bzl @@ -0,0 +1,38 @@ +load("@bazel_skylib//rules:write_file.bzl", "write_file") + +def update_doc(doc_provs, doc_path = "doc"): + """Defines an executable target that copies the documentation from the output directory to the workspace directory. + + Args: + doc_provs: A `list` of document provider `struct` values as returned + from `providers.create()`. + doc_path: The relative path for the documentation directory. Do not + include a leading or trailing slash. + + Returns: + None. + """ + write_file( + name = "gen_update", + out = "update.sh", + content = [ + "#!/usr/bin/env bash", + "cd $BUILD_WORKSPACE_DIRECTORY", + ] + [ + "cp -fv bazel-bin/{doc_path}/{gen_doc} {doc_path}/{src_doc}".format( + doc_path = doc_path, + gen_doc = doc_prov.out_basename, + src_doc = doc_prov.doc_basename, + ) + for doc_prov in doc_provs + ], + ) + + native.sh_binary( + name = "update", + srcs = ["update.sh"], + data = [doc_prov.out_basename for doc_prov in doc_provs], + # The '@' in the following visibility is important. It makes the + # target visible relative to the repository where it is being used. + visibility = ["@//visibility:public"], + ) diff --git a/bazeldoc/private/write_doc.bzl b/bazeldoc/private/write_doc.bzl new file mode 100644 index 00000000..8053bebe --- /dev/null +++ b/bazeldoc/private/write_doc.bzl @@ -0,0 +1,26 @@ +load("@bazel_skylib//rules:write_file.bzl", "write_file") + +def write_doc(name, out, content = [], do_not_edit_warning = True): + """Writes a documentation file with the specified content. + + Args: + name: The name of the target. + out: The basename of the output filename as a `string`. + content: A `list` of strings representing the content of the file. + do_not_edit_warning: A `bool` specifying whether a comment should be + added to the top of the written file. + + Returns: + None. + """ + final_content = [] + if do_not_edit_warning: + final_content.append("") + final_content.extend(content) + final_content.append("") + + write_file( + name = name, + out = out, + content = final_content, + ) diff --git a/bazeldoc/private/write_file_list.bzl b/bazeldoc/private/write_file_list.bzl new file mode 100644 index 00000000..666ff03a --- /dev/null +++ b/bazeldoc/private/write_file_list.bzl @@ -0,0 +1,48 @@ +load(":write_doc.bzl", "write_doc") +load(":doc_utilities.bzl", "doc_utilities") + +def write_file_list( + name, + out, + header_content = [], + doc_provs = [], + doc_path = "doc", + do_not_edit_warning = True): + """Defines a target that writes a documentation file that contains a header and a list of files. + + Args: + name: The name of the target. + out: The basename of the output filename as a `string`. + header_content: A `list` of strings representing the header content of + the file. + doc_provs: A `list` of document provider `struct` values as returned + from `providers.create()`. + doc_path: The relative path for the documentation directory. Do not + include a leading or trailing slash. + do_not_edit_warning: A `bool` specifying whether a comment should be + added to the top of the written file. + + Returns: + None. + """ + content = [] + content.extend(header_content) + if doc_provs != []: + content.extend([ + doc_utilities.toc_entry(r.name, "/{doc_path}/{src_doc}".format( + doc_path = doc_path, + src_doc = r.doc_basename, + )) + for r in doc_provs + ]) + content.append("") + + if out == None: + out = name + ".vm" + + write_doc( + name = name, + out = out, + content = content, + do_not_edit_warning = do_not_edit_warning, + ) diff --git a/bazeldoc/private/write_header.bzl b/bazeldoc/private/write_header.bzl new file mode 100644 index 00000000..abeffeae --- /dev/null +++ b/bazeldoc/private/write_header.bzl @@ -0,0 +1,45 @@ +load(":write_doc.bzl", "write_doc") +load(":doc_utilities.bzl", "doc_utilities") + +def write_header( + name, + out = None, + header_content = [], + symbols = [], + do_not_edit_warning = True): + """Defines a target that writes a header file that will be used as a header template for a `stardoc` rule. + + Args: + name: The name of the target. + out: The basename of the output filename as a `string`. + header_content: A `list` of strings representing the header content of + the file. + symbols: A `list` of symbol names that will be included in the documentation. + do_not_edit_warning: A `bool` specifying whether a comment should be + added to the top of the written file. + + Returns: + None. + """ + content = [] + content.extend(header_content) + if symbols != []: + content.extend([ + "", + "On this page:", + "", + ]) + content.extend( + [doc_utilities.toc_entry(s, "#{0}".format(s)) for s in symbols], + ) + content.append("") + + if out == None: + out = name + ".vm" + + write_doc( + name = name, + out = out, + content = content, + do_not_edit_warning = do_not_edit_warning, + ) diff --git a/bzlrelease/BUILD.bazel b/bzlrelease/BUILD.bazel new file mode 100644 index 00000000..4bfaa790 --- /dev/null +++ b/bzlrelease/BUILD.bazel @@ -0,0 +1,18 @@ +load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg") +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + +package(default_visibility = ["//visibility:public"]) + +bzlformat_pkg(name = "bzlformat") + +bzl_library( + name = "defs", + srcs = ["defs.bzl"], + deps = [ + "//bzlrelease/private:create_release", + "//bzlrelease/private:generate_release_notes", + "//bzlrelease/private:generate_workspace_snippet", + "//bzlrelease/private:hash_sha256", + "//bzlrelease/private:update_readme", + ], +) diff --git a/bzlrelease/defs.bzl b/bzlrelease/defs.bzl new file mode 100644 index 00000000..3778a645 --- /dev/null +++ b/bzlrelease/defs.bzl @@ -0,0 +1,27 @@ +load( + "//bzlrelease/private:generate_release_notes.bzl", + _generate_release_notes = "generate_release_notes", +) +load( + "//bzlrelease/private:generate_workspace_snippet.bzl", + _generate_workspace_snippet = "generate_workspace_snippet", +) +load("//bzlrelease/private:hash_sha256.bzl", _hash_sha256 = "hash_sha256") +load( + "//bzlrelease/private:update_readme.bzl", + _update_readme = "update_readme", +) +load( + "//bzlrelease/private:create_release.bzl", + _create_release = "create_release", +) + +create_release = _create_release + +generate_workspace_snippet = _generate_workspace_snippet + +generate_release_notes = _generate_release_notes + +hash_sha256 = _hash_sha256 + +update_readme = _update_readme diff --git a/bzlrelease/private/BUILD.bazel b/bzlrelease/private/BUILD.bazel new file mode 100644 index 00000000..8f8b53b3 --- /dev/null +++ b/bzlrelease/private/BUILD.bazel @@ -0,0 +1,43 @@ +load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg") +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + +bzlformat_pkg(name = "bzlformat") + +package(default_visibility = ["//bzlrelease:__subpackages__"]) + +bzl_library( + name = "hash_sha256", + srcs = ["hash_sha256.bzl"], +) + +bzl_library( + name = "generate_workspace_snippet", + srcs = ["generate_workspace_snippet.bzl"], + deps = [ + "//rules:execute_binary", + ], +) + +bzl_library( + name = "generate_release_notes", + srcs = ["generate_release_notes.bzl"], + deps = [ + "//rules:execute_binary", + ], +) + +bzl_library( + name = "update_readme", + srcs = ["update_readme.bzl"], + deps = [ + "//rules:execute_binary", + ], +) + +bzl_library( + name = "create_release", + srcs = ["create_release.bzl"], + deps = [ + "//rules:execute_binary", + ], +) diff --git a/bzlrelease/private/create_release.bzl b/bzlrelease/private/create_release.bzl new file mode 100644 index 00000000..a70851e8 --- /dev/null +++ b/bzlrelease/private/create_release.bzl @@ -0,0 +1,20 @@ +load("//rules/private:execute_binary.bzl", "execute_binary") + +def create_release(name, workflow_name): + """Declares an executable target that launches a Github Actions release workflow. + + This utility expects Github's CLI (`gh`) to be installed. Running this \ + utility launches a Github Actions workflow that creates a release tag, \ + generates release notes, creates a release, and creates a PR with an \ + updated README.md file. + + Args: + name: The name of the executable target as a `string`. + workflow_name: The name of the Github Actions workflow. + """ + arguments = ["--workflow", workflow_name] + execute_binary( + name = name, + arguments = arguments, + binary = "@cgrindel_bazel_starlib//tools:create_release", + ) diff --git a/rules/private/generate_release_notes.bzl b/bzlrelease/private/generate_release_notes.bzl similarity index 100% rename from rules/private/generate_release_notes.bzl rename to bzlrelease/private/generate_release_notes.bzl diff --git a/rules/private/generate_workspace_snippet.bzl b/bzlrelease/private/generate_workspace_snippet.bzl similarity index 100% rename from rules/private/generate_workspace_snippet.bzl rename to bzlrelease/private/generate_workspace_snippet.bzl diff --git a/rules/private/hash_sha256.bzl b/bzlrelease/private/hash_sha256.bzl similarity index 100% rename from rules/private/hash_sha256.bzl rename to bzlrelease/private/hash_sha256.bzl diff --git a/rules/private/update_readme.bzl b/bzlrelease/private/update_readme.bzl similarity index 100% rename from rules/private/update_readme.bzl rename to bzlrelease/private/update_readme.bzl diff --git a/deps.bzl b/deps.bzl index be442b74..582bd40d 100644 --- a/deps.bzl +++ b/deps.bzl @@ -5,19 +5,21 @@ def bazel_starlib_dependencies(): maybe( http_archive, name = "bazel_skylib", - sha256 = "1c531376ac7e5a180e0237938a2536de0c54d93f5c278634818e0efc952dd56c", urls = [ - "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/1.0.3/bazel-skylib-1.0.3.tar.gz", - "https://github.com/bazelbuild/bazel-skylib/releases/download/1.0.3/bazel-skylib-1.0.3.tar.gz", + "https://github.com/bazelbuild/bazel-skylib/releases/download/1.1.1/bazel-skylib-1.1.1.tar.gz", + "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/1.1.1/bazel-skylib-1.1.1.tar.gz", ], + sha256 = "c6966ec828da198c5d9adbaa94c05e3a1c7f21bd012a0b29ba8ddbccb2c93b0d", ) maybe( http_archive, - name = "cgrindel_bazel_doc", - sha256 = "3ccc6d205a7f834c5e89adcb4bc5091a9a07a69376107807eb9aea731ce92854", - strip_prefix = "bazel-doc-0.1.2", - urls = ["https://github.com/cgrindel/bazel-doc/archive/v0.1.2.tar.gz"], + name = "io_bazel_stardoc", + sha256 = "c9794dcc8026a30ff67cf7cf91ebe245ca294b20b071845d12c192afe243ad72", + urls = [ + "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz", + "https://github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz", + ], ) maybe( @@ -27,13 +29,3 @@ def bazel_starlib_dependencies(): strip_prefix = "rules_bzlformat-0.2.0", urls = ["https://github.com/cgrindel/rules_bzlformat/archive/v0.2.0.tar.gz"], ) - - maybe( - http_archive, - name = "rules_pkg", - sha256 = "a89e203d3cf264e564fcb96b6e06dd70bc0557356eb48400ce4b5d97c2c3720d", - urls = [ - "https://mirror.bazel.build/github.com/bazelbuild/rules_pkg/releases/download/0.5.1/rules_pkg-0.5.1.tar.gz", - "https://github.com/bazelbuild/rules_pkg/releases/download/0.5.1/rules_pkg-0.5.1.tar.gz", - ], - ) diff --git a/doc/BUILD.bazel b/doc/BUILD.bazel index 570ff3eb..35c1c812 100644 --- a/doc/BUILD.bazel +++ b/doc/BUILD.bazel @@ -1,6 +1,6 @@ load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg") load( - "@cgrindel_bazel_doc//bazeldoc:bazeldoc.bzl", + "//bazeldoc:defs.bzl", "doc_for_provs", "write_file_list", "write_header", @@ -15,10 +15,6 @@ _RULE_NAMES = [ "binary_pkg", "execute_binary", "filter_srcs", - "generate_release_notes", - "generate_workspace_snippet", - "hash_sha256", - "update_readme", "write_bazel_status_vars", ] diff --git a/doc/README.md b/doc/README.md index b9f7c33f..77c512fe 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,4 +1,10 @@ # Documentation for Starlib -- [API](/doc/api.md) -- [Rules](/doc/rules.md) +## Rule Sets Documentation +- [bazeldoc](bazeldoc/README.md) +- [bzlrelease](bzlrelease/README.md) + +## Other Documentation + +- [API](api.md) +- [Rules](rules.md) diff --git a/doc/bazeldoc/BUILD.bazel b/doc/bazeldoc/BUILD.bazel new file mode 100644 index 00000000..d0edecb4 --- /dev/null +++ b/doc/bazeldoc/BUILD.bazel @@ -0,0 +1,106 @@ +load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg") +load( + "//bazeldoc:defs.bzl", + "doc_for_provs", + "write_file_list", + "write_header", + doc_providers = "providers", +) + +bzlformat_pkg(name = "bzlformat") + +# Lovingly inspired by +# https://github.com/bazelbuild/rules_swift/blob/021c11b1d578ffba547140eb24854cdfe74c794f/doc/BUILD.bazel#L3 + +# MARK: - Documentation Declarations + +_API_SRCS = [ + "providers", +] + +_STARDOC_INPUT = "//bazeldoc:defs.bzl" + +_DOC_DEPS = [ + "//bazeldoc:defs", +] + +_DOC_PATH = "doc/bazeldoc" + +_API_DOC_PROVIDERS = [ + doc_providers.create( + name = name, + stardoc_input = _STARDOC_INPUT, + symbols = [name], + deps = _DOC_DEPS, + ) + for name in _API_SRCS +] + +_BUILD_RULES_PROV = doc_providers.create( + name = "build_rules_overview", + stardoc_input = _STARDOC_INPUT, + symbols = [ + "doc_for_provs", + "write_header", + "write_file_list", + ], + deps = _DOC_DEPS, +) + +_ALL_DOC_PROVIDERS = [ + _BUILD_RULES_PROV, + doc_providers.create( + name = "api", + is_stardoc = False, + stardoc_input = _STARDOC_INPUT, + deps = _DOC_DEPS, + ), +] + _API_DOC_PROVIDERS + +# MARK: - Special Case api.md + +write_file_list( + name = "api_doc", + out = "api.md_", + doc_path = _DOC_PATH, + doc_provs = _API_DOC_PROVIDERS, + header_content = [ + "# Documentation API", + "", + "The APIs described below are used by ", + "[the build rules](build_rules_overview.md) to facilitate the ", + "generation of the Starlark documentation.", + "", + ], +) + +# MARK: - Headers + +write_header( + name = "build_rules_overview_header", + header_content = [ + "# Build Rules", + "", + "The macros described below are used to generate, test and copy ", + "Starlark documentation.", + ], + symbols = _BUILD_RULES_PROV.symbols, +) + +# Write the API headers +[ + write_header( + name = doc_prov.header_label, + out = doc_prov.header_basename, + header_content = [ + "# `{name}` API".format(name = doc_prov.name), + ], + ) + for doc_prov in _API_DOC_PROVIDERS + if doc_prov.is_stardoc +] + +doc_for_provs( + doc_path = _DOC_PATH, + doc_provs = _ALL_DOC_PROVIDERS, +) diff --git a/doc/bazeldoc/README.md b/doc/bazeldoc/README.md new file mode 100644 index 00000000..a39a24d6 --- /dev/null +++ b/doc/bazeldoc/README.md @@ -0,0 +1,4 @@ +# Bazeldoc Documentation + +- [API documentation](api.md) +- [Build rules and macros](build_rules_overview.md) diff --git a/doc/bazeldoc/api.md b/doc/bazeldoc/api.md new file mode 100755 index 00000000..b2d5af1f --- /dev/null +++ b/doc/bazeldoc/api.md @@ -0,0 +1,9 @@ + +# Documentation API + +The APIs described below are used by +[the build rules](build_rules_overview.md) to facilitate the +generation of the Starlark documentation. + + * [providers](/doc/bazeldoc/providers.md) + diff --git a/doc/bazeldoc/build_rules_overview.md b/doc/bazeldoc/build_rules_overview.md new file mode 100755 index 00000000..804261d5 --- /dev/null +++ b/doc/bazeldoc/build_rules_overview.md @@ -0,0 +1,89 @@ + +# Build Rules + +The macros described below are used to generate, test and copy +Starlark documentation. + +On this page: + + * [doc_for_provs](#doc_for_provs) + * [write_header](#write_header) + * [write_file_list](#write_file_list) + + + + +## doc_for_provs + +
+doc_for_provs(doc_provs, doc_path)
+
+ +Defines targets for generating documentation, testing that the generated doc matches the workspace directory, and copying the generated doc to the workspace directory. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| doc_provs | A list of document provider struct values as returned from providers.create(). | none | +| doc_path |

-

| "doc" | + +**RETURNS** + +None. + + + + +## write_file_list + +
+write_file_list(name, out, header_content, doc_provs, doc_path, do_not_edit_warning)
+
+ +Defines a target that writes a documentation file that contains a header and a list of files. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| name | The name of the target. | none | +| out | The basename of the output filename as a string. | none | +| header_content | A list of strings representing the header content of the file. | [] | +| doc_provs | A list of document provider struct values as returned from providers.create(). | [] | +| doc_path | The relative path for the documentation directory. Do not include a leading or trailing slash. | "doc" | +| do_not_edit_warning | A bool specifying whether a comment should be added to the top of the written file. | True | + +**RETURNS** + +None. + + + + +## write_header + +
+write_header(name, out, header_content, symbols, do_not_edit_warning)
+
+ +Defines a target that writes a header file that will be used as a header template for a `stardoc` rule. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| name | The name of the target. | none | +| out | The basename of the output filename as a string. | None | +| header_content | A list of strings representing the header content of the file. | [] | +| symbols | A list of symbol names that will be included in the documentation. | [] | +| do_not_edit_warning | A bool specifying whether a comment should be added to the top of the written file. | True | + +**RETURNS** + +None. + + diff --git a/doc/bazeldoc/providers.md b/doc/bazeldoc/providers.md new file mode 100755 index 00000000..7fc90090 --- /dev/null +++ b/doc/bazeldoc/providers.md @@ -0,0 +1,36 @@ + +# `providers` API + + + + +## providers.create + +
+providers.create(name, stardoc_input, deps, doc_label, out_basename, doc_basename, header_label,
+                 header_basename, symbols, is_stardoc)
+
+ +Create a documentation provider. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| name | A string which identifies the doc output. If no symbols are provided, all of the symbols which are defined in the corresponding .bzl file are documented. | none | +| stardoc_input | A string representing the input label provided to the stardoc declaration. | none | +| deps | A list of deps for the stardoc rule. | none | +| doc_label | Optional. A string which is the doc label name. | None | +| out_basename | Optional. A string which is the basename for the output file. | None | +| doc_basename | Optional. A string which is the basename for the final documentation file. | None | +| header_label | Optional. A string which is the header label name, if the header is being generated. | None | +| header_basename | Optional. The basename (string) of the header filename file, if one is being used. | None | +| symbols | Optional. A list of symbol names that should be included in the documentation. | None | +| is_stardoc | A bool indicating whether a stardoc declaration should be created. | True | + +**RETURNS** + +A `struct` representing a documentation provider. + + diff --git a/doc/bzlrelease/BUILD.bazel b/doc/bzlrelease/BUILD.bazel new file mode 100644 index 00000000..4788879c --- /dev/null +++ b/doc/bzlrelease/BUILD.bazel @@ -0,0 +1,112 @@ +load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg") +load( + "//bazeldoc:defs.bzl", + "doc_for_provs", + "write_file_list", + "write_header", + doc_providers = "providers", +) + +bzlformat_pkg(name = "bzlformat") + +# MARK: - Documentation Providers + +_RULE_NAMES = [ + "create_release", + "generate_release_notes", + "generate_workspace_snippet", + "hash_sha256", + "update_readme", +] + +_RULE_DOC_PROVIDERS = [ + doc_providers.create( + name = rule, + stardoc_input = "//bzlrelease:defs.bzl", + symbols = [rule], + deps = ["//bzlrelease:defs"], + ) + for rule in _RULE_NAMES +] + +_API_SRCS = [] + +_API_DOC_PROVIDERS = [] + +_ALL_DOC_PROVIDERS = [ + doc_providers.create( + name = "api", + is_stardoc = False, + stardoc_input = "", + deps = [], + ), + doc_providers.create( + name = "rules", + is_stardoc = False, + stardoc_input = "", + deps = [], + ), +] + _RULE_DOC_PROVIDERS + _API_DOC_PROVIDERS + +# MARK: - Headers + +# Write rule headers +[ + write_header( + name = doc_prov.header_label, + out = doc_prov.header_basename, + header_content = [ + "# `{name}` Rule".format(name = doc_prov.name), + ], + ) + for doc_prov in _RULE_DOC_PROVIDERS + if doc_prov.is_stardoc +] + +# Write the API headers +[ + write_header( + name = doc_prov.header_label, + out = doc_prov.header_basename, + header_content = [ + "# `{name}` API".format(name = doc_prov.name), + ], + ) + for doc_prov in _API_DOC_PROVIDERS + if doc_prov.is_stardoc +] + +# MARK: - Special Case api.md + +# Write the api.md_ file as a special case. +write_file_list( + name = "api_doc", + out = "api.md_", + doc_provs = _API_DOC_PROVIDERS, + header_content = [ + "# Build API", + "", + "The APIs listed below are available in this repository.", + "", + ], +) + +# Write the rules.md_ file as a special case. +write_file_list( + name = "rules_doc", + out = "rules.md_", + doc_provs = _RULE_DOC_PROVIDERS, + header_content = [ + "# Rules", + "", + "The rules listed below are available in this repository.", + "", + ], +) + +# MARK: - Generate Documentation from Providers + +doc_for_provs( + doc_path = "doc/bzlrelease", + doc_provs = _ALL_DOC_PROVIDERS, +) diff --git a/doc/bzlrelease/README.md b/doc/bzlrelease/README.md new file mode 100644 index 00000000..c16b0727 --- /dev/null +++ b/doc/bzlrelease/README.md @@ -0,0 +1,4 @@ +# Bzlrelease Documentation + +- [API Documentation](api.md) +- [Rules Documentation](rules.md) diff --git a/doc/bzlrelease/api.md b/doc/bzlrelease/api.md new file mode 100755 index 00000000..be9afc6f --- /dev/null +++ b/doc/bzlrelease/api.md @@ -0,0 +1,6 @@ + +# Build API + +The APIs listed below are available in this repository. + + diff --git a/doc/bzlrelease/create_release.md b/doc/bzlrelease/create_release.md new file mode 100755 index 00000000..8b2580d2 --- /dev/null +++ b/doc/bzlrelease/create_release.md @@ -0,0 +1,26 @@ + +# `create_release` Rule + + + + +## create_release + +
+create_release(name, workflow_name)
+
+ +Declares an executable target that launches a Github Actions release workflow. + +This utility expects Github's CLI (`gh`) to be installed. Running this utility launches a Github Actions workflow that creates a release tag, generates release notes, creates a release, and creates a PR with an updated README.md file. + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| name | The name of the executable target as a string. | none | +| workflow_name | The name of the Github Actions workflow. | none | + + diff --git a/doc/generate_release_notes.md b/doc/bzlrelease/generate_release_notes.md similarity index 100% rename from doc/generate_release_notes.md rename to doc/bzlrelease/generate_release_notes.md diff --git a/doc/generate_workspace_snippet.md b/doc/bzlrelease/generate_workspace_snippet.md similarity index 100% rename from doc/generate_workspace_snippet.md rename to doc/bzlrelease/generate_workspace_snippet.md diff --git a/doc/hash_sha256.md b/doc/bzlrelease/hash_sha256.md similarity index 100% rename from doc/hash_sha256.md rename to doc/bzlrelease/hash_sha256.md diff --git a/doc/bzlrelease/rules.md b/doc/bzlrelease/rules.md new file mode 100755 index 00000000..908f69a3 --- /dev/null +++ b/doc/bzlrelease/rules.md @@ -0,0 +1,11 @@ + +# Rules + +The rules listed below are available in this repository. + + * [create_release](/doc/create_release.md) + * [generate_release_notes](/doc/generate_release_notes.md) + * [generate_workspace_snippet](/doc/generate_workspace_snippet.md) + * [hash_sha256](/doc/hash_sha256.md) + * [update_readme](/doc/update_readme.md) + diff --git a/doc/update_readme.md b/doc/bzlrelease/update_readme.md similarity index 100% rename from doc/update_readme.md rename to doc/bzlrelease/update_readme.md diff --git a/doc/rules.md b/doc/rules.md index d51d7073..621d76ab 100755 --- a/doc/rules.md +++ b/doc/rules.md @@ -6,9 +6,5 @@ The rules listed below are available in this repository. * [binary_pkg](/doc/binary_pkg.md) * [execute_binary](/doc/execute_binary.md) * [filter_srcs](/doc/filter_srcs.md) - * [generate_release_notes](/doc/generate_release_notes.md) - * [generate_workspace_snippet](/doc/generate_workspace_snippet.md) - * [hash_sha256](/doc/hash_sha256.md) - * [update_readme](/doc/update_readme.md) * [write_bazel_status_vars](/doc/write_bazel_status_vars.md) diff --git a/release/BUILD.bazel b/release/BUILD.bazel new file mode 100644 index 00000000..40b5f3af --- /dev/null +++ b/release/BUILD.bazel @@ -0,0 +1,33 @@ +load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg") +load( + "//bzlrelease:defs.bzl", + "create_release", + "generate_release_notes", + "generate_workspace_snippet", + "update_readme", +) +load("//rules/private:execute_binary.bzl", "execute_binary", "file_placeholder") + +bzlformat_pkg(name = "bzlformat") + +# MARK: - Release + +generate_workspace_snippet( + name = "generate_workspace_snippet", + template = "workspace_snippet.tmpl", +) + +generate_release_notes( + name = "generate_release_notes", + generate_workspace_snippet = ":generate_workspace_snippet", +) + +update_readme( + name = "update_readme", + generate_workspace_snippet = ":generate_workspace_snippet", +) + +create_release( + name = "create", + workflow_name = "Create Release", +) diff --git a/release/README.md b/release/README.md new file mode 100644 index 00000000..0e9280ec --- /dev/null +++ b/release/README.md @@ -0,0 +1,3 @@ +# Release Process for Bazel-Starlib + +GH004: Add release documentation diff --git a/tests/rules_tests/generate_release_notes_tests/workspace_snippet.tmpl b/release/workspace_snippet.tmpl similarity index 79% rename from tests/rules_tests/generate_release_notes_tests/workspace_snippet.tmpl rename to release/workspace_snippet.tmpl index 5edeb017..d71cbe48 100644 --- a/tests/rules_tests/generate_release_notes_tests/workspace_snippet.tmpl +++ b/release/workspace_snippet.tmpl @@ -10,10 +10,6 @@ load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace") bazel_skylib_workspace() -load("@cgrindel_bazel_doc//bazeldoc:deps.bzl", "bazeldoc_dependencies") - -bazeldoc_dependencies() - load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories") stardoc_repositories() diff --git a/rules/BUILD.bazel b/rules/BUILD.bazel index e4cbabdd..fabd7f86 100644 --- a/rules/BUILD.bazel +++ b/rules/BUILD.bazel @@ -13,14 +13,6 @@ bzl_library( ], ) -bzl_library( - name = "hash_sha256", - srcs = ["hash_sha256.bzl"], - deps = [ - "//rules/private:hash_sha256", - ], -) - bzl_library( name = "write_bazel_status_vars", srcs = ["write_bazel_status_vars.bzl"], @@ -44,27 +36,3 @@ bzl_library( "//rules/private:execute_binary", ], ) - -bzl_library( - name = "generate_workspace_snippet", - srcs = ["generate_workspace_snippet.bzl"], - deps = [ - "//rules/private:generate_workspace_snippet", - ], -) - -bzl_library( - name = "generate_release_notes", - srcs = ["generate_release_notes.bzl"], - deps = [ - "//rules/private:generate_release_notes", - ], -) - -bzl_library( - name = "update_readme", - srcs = ["update_readme.bzl"], - deps = [ - "//rules/private:update_readme", - ], -) diff --git a/rules/generate_release_notes.bzl b/rules/generate_release_notes.bzl deleted file mode 100644 index dd1c7721..00000000 --- a/rules/generate_release_notes.bzl +++ /dev/null @@ -1,6 +0,0 @@ -load( - "//rules/private:generate_release_notes.bzl", - _generate_release_notes = "generate_release_notes", -) - -generate_release_notes = _generate_release_notes diff --git a/rules/generate_workspace_snippet.bzl b/rules/generate_workspace_snippet.bzl deleted file mode 100644 index 970664fe..00000000 --- a/rules/generate_workspace_snippet.bzl +++ /dev/null @@ -1,6 +0,0 @@ -load( - "//rules/private:generate_workspace_snippet.bzl", - _generate_workspace_snippet = "generate_workspace_snippet", -) - -generate_workspace_snippet = _generate_workspace_snippet diff --git a/rules/hash_sha256.bzl b/rules/hash_sha256.bzl deleted file mode 100644 index 9fe46581..00000000 --- a/rules/hash_sha256.bzl +++ /dev/null @@ -1,3 +0,0 @@ -load("//rules/private:hash_sha256.bzl", _hash_sha256 = "hash_sha256") - -hash_sha256 = _hash_sha256 diff --git a/rules/private/BUILD.bazel b/rules/private/BUILD.bazel index 7dc33c5a..19186423 100644 --- a/rules/private/BUILD.bazel +++ b/rules/private/BUILD.bazel @@ -12,11 +12,6 @@ bzl_library( srcs = ["filter_srcs.bzl"], ) -bzl_library( - name = "hash_sha256", - srcs = ["hash_sha256.bzl"], -) - bzl_library( name = "write_bazel_status_vars", srcs = ["write_bazel_status_vars.bzl"], @@ -30,14 +25,6 @@ bzl_library( ], ) -bzl_library( - name = "generate_workspace_snippet", - srcs = ["generate_workspace_snippet.bzl"], - deps = [ - ":execute_binary", - ], -) - bzl_library( name = "binary_pkg", srcs = ["binary_pkg.bzl"], @@ -45,19 +32,3 @@ bzl_library( "@bazel_skylib//lib:paths", ], ) - -bzl_library( - name = "generate_release_notes", - srcs = ["generate_release_notes.bzl"], - deps = [ - ":execute_binary", - ], -) - -bzl_library( - name = "update_readme", - srcs = ["update_readme.bzl"], - deps = [ - ":execute_binary", - ], -) diff --git a/rules/update_readme.bzl b/rules/update_readme.bzl deleted file mode 100644 index 94a79e91..00000000 --- a/rules/update_readme.bzl +++ /dev/null @@ -1,6 +0,0 @@ -load( - "//rules/private:update_readme.bzl", - _update_readme = "update_readme", -) - -update_readme = _update_readme diff --git a/tests/rules_tests/generate_release_notes_tests/BUILD.bazel b/tests/bzlrelease_tests/rules_tests/generate_release_notes_tests/BUILD.bazel similarity index 87% rename from tests/rules_tests/generate_release_notes_tests/BUILD.bazel rename to tests/bzlrelease_tests/rules_tests/generate_release_notes_tests/BUILD.bazel index 80e10912..f66e9fe0 100644 --- a/tests/rules_tests/generate_release_notes_tests/BUILD.bazel +++ b/tests/bzlrelease_tests/rules_tests/generate_release_notes_tests/BUILD.bazel @@ -1,6 +1,5 @@ load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg") -load("//rules:generate_release_notes.bzl", "generate_release_notes") -load("//rules:generate_workspace_snippet.bzl", "generate_workspace_snippet") +load("//bzlrelease:defs.bzl", "generate_release_notes", "generate_workspace_snippet") load("//tests:integration_test_common.bzl", "GH_ENV_INHERIT", "INTEGRATION_TEST_TAGS") bzlformat_pkg(name = "bzlformat") diff --git a/tests/rules_tests/generate_release_notes_tests/generate_release_notes_test.sh b/tests/bzlrelease_tests/rules_tests/generate_release_notes_tests/generate_release_notes_test.sh similarity index 94% rename from tests/rules_tests/generate_release_notes_tests/generate_release_notes_test.sh rename to tests/bzlrelease_tests/rules_tests/generate_release_notes_tests/generate_release_notes_test.sh index 8de6d762..41ef8751 100755 --- a/tests/rules_tests/generate_release_notes_tests/generate_release_notes_test.sh +++ b/tests/bzlrelease_tests/rules_tests/generate_release_notes_tests/generate_release_notes_test.sh @@ -18,7 +18,7 @@ setup_git_repo_sh_location=cgrindel_bazel_starlib/tests/setup_git_repo.sh setup_git_repo_sh="$(rlocation "${setup_git_repo_sh_location}")" || \ (echo >&2 "Failed to locate ${setup_git_repo_sh_location}" && exit 1) -generate_release_notes_sh_location=cgrindel_bazel_starlib/tests/rules_tests/generate_release_notes_tests/generate_release_notes.sh +generate_release_notes_sh_location=cgrindel_bazel_starlib/tests/bzlrelease_tests/rules_tests/generate_release_notes_tests/generate_release_notes.sh generate_release_notes_sh="$(rlocation "${generate_release_notes_sh_location}")" || \ (echo >&2 "Failed to locate ${generate_release_notes_sh_location}" && exit 1) diff --git a/tests/rules_tests/generate_workspace_snippet_tests/workspace_snippet.tmpl b/tests/bzlrelease_tests/rules_tests/generate_release_notes_tests/workspace_snippet.tmpl similarity index 79% rename from tests/rules_tests/generate_workspace_snippet_tests/workspace_snippet.tmpl rename to tests/bzlrelease_tests/rules_tests/generate_release_notes_tests/workspace_snippet.tmpl index 5edeb017..d71cbe48 100644 --- a/tests/rules_tests/generate_workspace_snippet_tests/workspace_snippet.tmpl +++ b/tests/bzlrelease_tests/rules_tests/generate_release_notes_tests/workspace_snippet.tmpl @@ -10,10 +10,6 @@ load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace") bazel_skylib_workspace() -load("@cgrindel_bazel_doc//bazeldoc:deps.bzl", "bazeldoc_dependencies") - -bazeldoc_dependencies() - load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories") stardoc_repositories() diff --git a/tests/rules_tests/generate_workspace_snippet_tests/BUILD.bazel b/tests/bzlrelease_tests/rules_tests/generate_workspace_snippet_tests/BUILD.bazel similarity index 92% rename from tests/rules_tests/generate_workspace_snippet_tests/BUILD.bazel rename to tests/bzlrelease_tests/rules_tests/generate_workspace_snippet_tests/BUILD.bazel index 488167a8..ea145f40 100644 --- a/tests/rules_tests/generate_workspace_snippet_tests/BUILD.bazel +++ b/tests/bzlrelease_tests/rules_tests/generate_workspace_snippet_tests/BUILD.bazel @@ -1,5 +1,5 @@ load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg") -load("//rules:generate_workspace_snippet.bzl", "generate_workspace_snippet") +load("//bzlrelease:defs.bzl", "generate_workspace_snippet") load("//tests:integration_test_common.bzl", "GH_ENV_INHERIT", "INTEGRATION_TEST_TAGS") bzlformat_pkg(name = "bzlformat") diff --git a/tests/rules_tests/generate_workspace_snippet_tests/generate_workspace_snippet_test.sh b/tests/bzlrelease_tests/rules_tests/generate_workspace_snippet_tests/generate_workspace_snippet_test.sh similarity index 88% rename from tests/rules_tests/generate_workspace_snippet_tests/generate_workspace_snippet_test.sh rename to tests/bzlrelease_tests/rules_tests/generate_workspace_snippet_tests/generate_workspace_snippet_test.sh index d324a6e7..a7920203 100755 --- a/tests/rules_tests/generate_workspace_snippet_tests/generate_workspace_snippet_test.sh +++ b/tests/bzlrelease_tests/rules_tests/generate_workspace_snippet_tests/generate_workspace_snippet_test.sh @@ -20,11 +20,11 @@ setup_git_repo_sh_location=cgrindel_bazel_starlib/tests/setup_git_repo.sh setup_git_repo_sh="$(rlocation "${setup_git_repo_sh_location}")" || \ (echo >&2 "Failed to locate ${setup_git_repo_sh_location}" && exit 1) -without_template_sh_location=cgrindel_bazel_starlib/tests/rules_tests/generate_workspace_snippet_tests/without_template.sh +without_template_sh_location=cgrindel_bazel_starlib/tests/bzlrelease_tests/rules_tests/generate_workspace_snippet_tests/without_template.sh without_template_sh="$(rlocation "${without_template_sh_location}")" || \ (echo >&2 "Failed to locate ${without_template_sh_location}" && exit 1) -with_template_sh_location=cgrindel_bazel_starlib/tests/rules_tests/generate_workspace_snippet_tests/with_template.sh +with_template_sh_location=cgrindel_bazel_starlib/tests/bzlrelease_tests/rules_tests/generate_workspace_snippet_tests/with_template.sh with_template_sh="$(rlocation "${with_template_sh_location}")" || \ (echo >&2 "Failed to locate ${with_template_sh_location}" && exit 1) diff --git a/tests/rules_tests/update_readme_tests/workspace_snippet.tmpl b/tests/bzlrelease_tests/rules_tests/generate_workspace_snippet_tests/workspace_snippet.tmpl similarity index 79% rename from tests/rules_tests/update_readme_tests/workspace_snippet.tmpl rename to tests/bzlrelease_tests/rules_tests/generate_workspace_snippet_tests/workspace_snippet.tmpl index 5edeb017..d71cbe48 100644 --- a/tests/rules_tests/update_readme_tests/workspace_snippet.tmpl +++ b/tests/bzlrelease_tests/rules_tests/generate_workspace_snippet_tests/workspace_snippet.tmpl @@ -10,10 +10,6 @@ load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace") bazel_skylib_workspace() -load("@cgrindel_bazel_doc//bazeldoc:deps.bzl", "bazeldoc_dependencies") - -bazeldoc_dependencies() - load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories") stardoc_repositories() diff --git a/tests/rules_tests/hash_sha256_tests/BUILD.bazel b/tests/bzlrelease_tests/rules_tests/hash_sha256_tests/BUILD.bazel similarity index 95% rename from tests/rules_tests/hash_sha256_tests/BUILD.bazel rename to tests/bzlrelease_tests/rules_tests/hash_sha256_tests/BUILD.bazel index 8979868c..542d7042 100644 --- a/tests/rules_tests/hash_sha256_tests/BUILD.bazel +++ b/tests/bzlrelease_tests/rules_tests/hash_sha256_tests/BUILD.bazel @@ -1,5 +1,5 @@ load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg") -load("//rules:hash_sha256.bzl", "hash_sha256") +load("//bzlrelease:defs.bzl", "hash_sha256") load("@bazel_skylib//rules:write_file.bzl", "write_file") bzlformat_pkg(name = "bzlformat") diff --git a/tests/rules_tests/hash_sha256_tests/data.txt b/tests/bzlrelease_tests/rules_tests/hash_sha256_tests/data.txt similarity index 100% rename from tests/rules_tests/hash_sha256_tests/data.txt rename to tests/bzlrelease_tests/rules_tests/hash_sha256_tests/data.txt diff --git a/tests/rules_tests/hash_sha256_tests/hash_sha256_test.sh b/tests/bzlrelease_tests/rules_tests/hash_sha256_tests/hash_sha256_test.sh similarity index 100% rename from tests/rules_tests/hash_sha256_tests/hash_sha256_test.sh rename to tests/bzlrelease_tests/rules_tests/hash_sha256_tests/hash_sha256_test.sh diff --git a/tests/rules_tests/update_readme_tests/BUILD.bazel b/tests/bzlrelease_tests/rules_tests/update_readme_tests/BUILD.bazel similarity index 88% rename from tests/rules_tests/update_readme_tests/BUILD.bazel rename to tests/bzlrelease_tests/rules_tests/update_readme_tests/BUILD.bazel index ac1cf7b0..d98e9827 100644 --- a/tests/rules_tests/update_readme_tests/BUILD.bazel +++ b/tests/bzlrelease_tests/rules_tests/update_readme_tests/BUILD.bazel @@ -1,6 +1,5 @@ load("@cgrindel_rules_bzlformat//bzlformat:bzlformat.bzl", "bzlformat_pkg") -load("//rules:update_readme.bzl", "update_readme") -load("//rules:generate_workspace_snippet.bzl", "generate_workspace_snippet") +load("//bzlrelease:defs.bzl", "generate_workspace_snippet", "update_readme") load("//tests:integration_test_common.bzl", "GH_ENV_INHERIT", "INTEGRATION_TEST_TAGS") bzlformat_pkg(name = "bzlformat") diff --git a/tests/rules_tests/update_readme_tests/update_readme_test.sh b/tests/bzlrelease_tests/rules_tests/update_readme_tests/update_readme_test.sh similarity index 95% rename from tests/rules_tests/update_readme_tests/update_readme_test.sh rename to tests/bzlrelease_tests/rules_tests/update_readme_tests/update_readme_test.sh index 1f2033f6..201d4ffd 100755 --- a/tests/rules_tests/update_readme_tests/update_readme_test.sh +++ b/tests/bzlrelease_tests/rules_tests/update_readme_tests/update_readme_test.sh @@ -22,7 +22,7 @@ setup_git_repo_sh_location=cgrindel_bazel_starlib/tests/setup_git_repo.sh setup_git_repo_sh="$(rlocation "${setup_git_repo_sh_location}")" || \ (echo >&2 "Failed to locate ${setup_git_repo_sh_location}" && exit 1) -update_readme_sh_location=cgrindel_bazel_starlib/tests/rules_tests/update_readme_tests/update_readme.sh +update_readme_sh_location=cgrindel_bazel_starlib/tests/bzlrelease_tests/rules_tests/update_readme_tests/update_readme.sh update_readme_sh="$(rlocation "${update_readme_sh_location}")" || \ (echo >&2 "Failed to locate ${update_readme_sh_location}" && exit 1) diff --git a/workspace_snippet.tmpl b/tests/bzlrelease_tests/rules_tests/update_readme_tests/workspace_snippet.tmpl similarity index 79% rename from workspace_snippet.tmpl rename to tests/bzlrelease_tests/rules_tests/update_readme_tests/workspace_snippet.tmpl index 5edeb017..d71cbe48 100644 --- a/workspace_snippet.tmpl +++ b/tests/bzlrelease_tests/rules_tests/update_readme_tests/workspace_snippet.tmpl @@ -10,10 +10,6 @@ load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace") bazel_skylib_workspace() -load("@cgrindel_bazel_doc//bazeldoc:deps.bzl", "bazeldoc_dependencies") - -bazeldoc_dependencies() - load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories") stardoc_repositories() diff --git a/tests/tools_tests/workspace_snippet.tmpl b/tests/tools_tests/workspace_snippet.tmpl index 5edeb017..d71cbe48 100644 --- a/tests/tools_tests/workspace_snippet.tmpl +++ b/tests/tools_tests/workspace_snippet.tmpl @@ -10,10 +10,6 @@ load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace") bazel_skylib_workspace() -load("@cgrindel_bazel_doc//bazeldoc:deps.bzl", "bazeldoc_dependencies") - -bazeldoc_dependencies() - load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories") stardoc_repositories() diff --git a/tools/create_release.sh b/tools/create_release.sh index e617b407..51da37c0 100755 --- a/tools/create_release.sh +++ b/tools/create_release.sh @@ -39,7 +39,7 @@ source "${github_sh}" is_installed gh || fail "Could not find Github CLI (gh)." -# MARK - Process Arguments +# MARK - Usage get_usage() { local utility="$(basename "${BASH_SOURCE[0]}")" @@ -47,16 +47,37 @@ get_usage() { Execute a Github Action workflow to create a relase with the specified tag. Usage: -${utility} +${utility} --worklfow [OPTION]... + +Required: + --workflow The name of the Github Actions workflow that will create + the release. + The release tag. + +Options: + --ref The ref (e.g. branch) from which to run the workflow. + --reset_tag If specified and if a release does not exist for the tag, + the existing tag will be deleted and a new one created. EOF )" } + +# MARK - Process Arguments + reset_tag=false args=() while (("$#")); do case "${1}" in + "--help") + show_usage + exit 0 + ;; + --workflow) + workflow_name="${2}" + shift 2 + ;; --ref) ref="${2}" shift 2 @@ -75,6 +96,8 @@ while (("$#")); do esac done +[[ -z "${workflow_name:-}" ]] && usage_error "Expected a workflow name." + [[ ${#args[@]} == 0 ]] && usage_error "Expected a version tag for the release. (e.g v.1.2.3)" tag="${args[0]}" is_valid_release_tag "${tag}" || fail "Invalid version tag. Expected it to start with 'v'." @@ -85,7 +108,7 @@ is_valid_release_tag "${tag}" || fail "Invalid version tag. Expected it to start cd "${BUILD_WORKSPACE_DIRECTORY}" # Launch the workflow -gh_cmd=(gh workflow run 'Create Release') +gh_cmd=(gh workflow run "${workflow_name}") [[ -z "${ref:-}" ]] || gh_cmd+=(--ref "${ref}") gh_cmd+=(-f "release_tag=${tag}") gh_cmd+=(-f "reset_tag=${reset_tag}")