Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(deploying.md): refer to rules-template #19667

Closed
wants to merge 1 commit into from
Closed

docs(deploying.md): refer to rules-template #19667

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 16 additions & 24 deletions site/en/rules/deploying.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
<https://github.com/bazel-contrib/rules-template>
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.
Expand All @@ -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:
Expand All @@ -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

Expand Down Expand Up @@ -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)
Expand All @@ -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?
Expand Down
Loading