Contributing to buildtools

Want to contribute? Great! First, read this page.

Before you contribute

Before you start working on a larger contribution, you should get in touch with us first through the issue tracker with your idea so that we can help out and possibly guide you. Coordinating up front makes it much easier to avoid frustration later on.

Building and testing

The repository is built with Bazel. Use Bazelisk to get the version pinned in .bazelversion. The Go toolchain is managed by Bazel, so you don't need a local Go installation.

Run the full test suite, which is what CI runs on Linux, macOS and Windows:

bazel test //...

Other commands you may need:

  • After adding, removing or renaming Go files or imports, regenerate the BUILD.bazel files:

    bazel run //:gazelle

  • After changing Go dependencies, tidy go.mod, go.sum and MODULE.bazel. CI fails if they are out of date:

    bazel run @io_bazel_rules_go//go -- mod tidy

  • Go code must be formatted with gofmt. Starlark files in this repository must be formatted with buildifier itself, either via pre-commit (pre-commit install) or by running:

    bazel run //:buildifier

Generated files

Some generated files are checked in, and tests fail if they are stale:

  • Protobuf bindings (*.gen.pb.go) and lang/tables.gen.go:

    ./update_generated.sh

  • WARNINGS.md, after editing warn/docs/warnings.textproto:

    bazel build //warn/docs:warnings_docs && cp bazel-bin/warn/docs/WARNINGS.md .

  • build/parse.y.go, after editing the grammar in build/parse.y:

    bazel build //build:parse.y.go_yacc && tail -n +3 bazel-bin/build/parse.y.baz.go > build/parse.y.go

Adding a linter warning

Register the warning in one of the warning maps in warn/warn.go, add tests next to the implementation, document it in warn/docs/warnings.textproto and regenerate WARNINGS.md as described above. A test checks that every warning is documented.

Pull requests

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Pull requests are squash-merged, so the pull request title and description become the commit message.

Before you open a pull request, please make sure that:

  • The change is small and focused. Read Google‘s engineering practices on small changes; if your change can’t follow them, explain why in the description.
  • The description explains what the change does and why, following Google's guidance on writing good descriptions.
  • The code is covered by unit or integration tests.
  • If you tested the change in ways that aren't captured by automated tests, the description includes the steps to reproduce that testing.
  • bazel test //... passes and all generated files are up to date.