layout: documentation title: Skylark Design Review Process

Skylark Design Review Process

Authors: Dmitry Lomov, Laurent Le Brun, Florian Weikert

Motivation

As Bazel adoption grows, we are seeing both more requests for adding features to Skylark as a language, and for exposing more and more functionality available in Bazel internally to Skylark extensions. These requests originate both within and outside the Bazel team. As their number grows (and we expect them to grow more and more over time), addressing those requests meets several challenges:

  • We need to keep Skylark as a language (and a set of associated APIs/libraries) concise and consistent, easy to learn and use, and documented.

  • Any APIs or solutions we adopt will be painful to change down the road, so the more consistent, orthogonal, and open to future extensions they are, the less pain we and our users will encounter.

  • It is difficult for engineers - both within the team and outside - to approach making changes to Skylark. As people attempt to do so, they experience a lot of friction: patches get written and the discussion starts where reviewers and the author attempt to solve Skylark API issues, code design issues, implementation issues, compatibility issues and so on and so forth all in one code review thread. The result is friction and frustration, and the quality of the end result is not guaranteed.

This document proposes an informal but orderly and well-defined process for Skylark language changes to address the above challenges.

Goals

  • Facilitate healthy growth of Skylark as a language

  • Ensure that Skylark the language has a clear set of experts caring for its development

  • Reduce friction for engineers exposing APIs to Skylark or proposing new Skylark features

Non-goals

  • Replace general design review process in Bazel team. The process described here is strictly about the Skylark language and APIs. In particular, changes to native rules that do not affect Skylark as a language much, such as adding/removing an attribute, or adding a new native rule, are not required to go through this process (whereas exposing a new provider to Skylark from a native rule is).

The Process

Changes to Skylark, both the language and the exposed APIs, are evaluated by the Skylark Reviewers Panel.

  1. The author of the proposed change sends the design document to the [bazel-dev@googlegroups.com] mailing list with a subject containing “SKYLARK DESIGN REVIEW”

  2. Design doc can be either of:

    1. A universally-commentable Google Doc
    2. A Gerrit code review request with a design doc in Markdown format.

  3. The design doc should include:

    1. Motivation for the change (a GitHub issue link is acceptable)
    2. An example of the usage of the proposed API/language feature
    3. Description of the proposed change

    A model example design doc (although that is probably an overkill).

  4. Skylark Reviewers respond to a document within 2 business days

  5. Skylark Reviewers are responsible for bringing in subject-matter experts as needed (for example, a change involving exposing a certain provider from cc_library rule should be reviewed by C++ rules expert as well)

  6. Skylark Reviewers facilitate the discussion and aim to reach a “looks good/does not look good” decision within 10 business days.

  7. Skylark Reviewers operate by consensus.