Deploying Rules

This documentation is for rule writers who are planning to make their
rules available to others.

Hosting and naming rules

New rules should go into their own GitHub repository under your organization.
Contact the bazel-dev mailing list
if you feel like your rules belong in the bazelbuild
organization.

Repository names for Bazel rules are standardized on the following format:
*/rules_*.
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.

Make sure to use a descriptive GitHub repository description and README.html
title, example:

Repository: bazelbuild/rules_go

Repository description: “Go rules for Bazel”

Repository tags: golang, bazel

README.html header: “Go rules for Bazel”
(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 (e.g., Scala) or some notion of platform
(e.g., Android.

Rule content

Every rule repository should have a certain layout so that users can quickly
understand new rules.

For example, suppose we are writing new rules for the (make-believe)
mockascript language. We would have the following structure:

README.html

At the top level, there should be a README.html that contains (at least) what
users will need to copy-paste into their WORKSPACE file to use your rule.
In general, this will be a git_repository pointing to your GitHub repo and
a macro call that downloads/configures any tools your rule needs. For example,
for the Go
rules, this
looks like:

Right now Bazel has to be compiled from source, as Travis does not support a
version of GCC that works with the precompiled Bazel binaries. Thus, the
before_install steps download the Bazel source, compile it, and “install” the
Bazel binary in /usr/bin.

Documentation

See the Skydoc documentation for
instructions on how to comment your rules so that documentation can be generated
automatically.

FAQs

Why can’t we add our rule to the main Bazel GitHub repository?

We want to decouple rules from Bazel releases as much as possible. It’s clearer
who owns individual rules, reducing the load on Bazel developers. For our users,
decoupling makes it easier to modify, upgrade, downgrade, and replace rules.
Contributing to rules can be lighter weight than contributing to Bazel -
depending on the rules -, including full submit access to the corresponding
GitHub repository. Getting submit access to Bazel itself is a much more involved
process.

The downside is a more complicated one-time installation process for our users:
they have to copy-paste a rule into their WORKSPACE file, as shown in the
README section above.

We used to have all of the rules in the Bazel repository (under
//tools/build_rules or //tools/build_defs). We still have a couple rules
there, but we are working on moving the remaining rules out.