From a2bf66a7559a1c2844046065e2e021757fc0c24f Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Thu, 28 Sep 2023 08:49:20 -0700 Subject: [PATCH] docs(deploying.md): refer to rules-template That repo is owned and carefully maintained by the Rules Authors SIG and saves a TON of time for rules developers. --- site/en/rules/deploying.md | 40 +++++++++++++++----------------------- 1 file changed, 16 insertions(+), 24 deletions(-) diff --git a/site/en/rules/deploying.md b/site/en/rules/deploying.md index 0d1b24b49fcb29..311ae96f4f0ff2 100644 --- a/site/en/rules/deploying.md +++ b/site/en/rules/deploying.md @@ -8,6 +8,11 @@ Book: /_book.yaml This page is for rule writers who are planning to make their rules available to others. +We recommend you start a new ruleset from the template repository: + +That template follows the recommendations below, and includes API documentation generation +and sets up a CI/CD pipeline to make it trivial to distribute your ruleset. + ## Hosting and naming rules New rules should go into their own GitHub repository under your organization. @@ -18,7 +23,7 @@ organization. Repository names for Bazel rules are standardized on the following format: `$ORGANIZATION/rules_$NAME`. See [examples on GitHub](https://github.com/search?q=rules+bazel&type=Repositories). -For consistency, you must follow this same format when publishing your Bazel rules. +For consistency, you should follow this same format when publishing your Bazel rules. Make sure to use a descriptive GitHub repository description and `README.md` title, example: @@ -30,8 +35,8 @@ title, example: (note the link to https://bazel.build which will guide users who are unfamiliar with Bazel to the right place) -Rules can be grouped either by language (such as Scala) or platform -(such as Android). +Rules can be grouped either by language (such as Scala), runtime platform +(such as Android), or framework (such as Spring). ## Repository content @@ -232,28 +237,11 @@ can either be in the standard location for the language the rules are for or a It is useful to users to have an `examples/` directory that shows users a couple of basic ways that the rules can be used. -## Testing +## CI/CD -Set up Travis as described in their [getting started -docs](https://docs.travis-ci.com/user/getting-started/). Then add a -`.travis.yml` file to your repository with the following content: - -``` -dist: xenial # Ubuntu 16.04 - -# On trusty (or later) images, the Bazel apt repository can be used. -addons: - apt: - sources: - - sourceline: 'deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8' - key_url: 'https://bazel.build/bazel-release.pub.gpg' - packages: - - bazel - -script: - - bazel build //... - - bazel test //... -``` +Many rulesets use GitHub Actions. See the configuration used in the [rules-template](https://github.com/bazel-contrib/rules-template/tree/main/.github/workflows) repo, which are simplified using a "reusable workflow" hosted in the bazel-contrib +org. `ci.yaml` runs tests on each PR and `main` comit, and `release.yaml` runs anytime you push a tag to the repository. +See comments in the rules-template repo for more information. If your repository is under the [bazelbuild organization](https://github.com/bazelbuild), you can [ask to add](https://github.com/bazelbuild/continuous-integration/issues/new?template=adding-your-project-to-bazel-ci.md&title=Request+to+add+new+project+%5BPROJECT_NAME%5D&labels=new-project) @@ -265,6 +253,10 @@ See the [Stardoc documentation](https://github.com/bazelbuild/stardoc) for instructions on how to comment your rules so that documentation can be generated automatically. +The [rules-template docs/ folder](https://github.com/bazel-contrib/rules-template/tree/main/docs) +shows a simple way to ensure the Markdown content in the `docs/` folder is always up-to-date +as Starlark files are updated. + ## FAQs ### Why can't we add our rule to the main Bazel GitHub repository?