Release notes

This document is targeted at Bazel contributors.

Commit descriptions in Bazel include a RELNOTES: tag followed by a release note. This is used by the Bazel team to track changes in each release and write the release announcement.

Overview

  • Is your change a bugfix? In that case, you don’t need a release note. Please include a reference to the GitHub issue.

  • If the change adds / removes / changes Bazel in a user-visible way, then it may be advantageous to mention it.

If the change is significant, please follow the design document policy first.

Guidelines

The release notes will be read by our users, so it should be short (ideally one sentence), avoid jargon (Bazel-internal terminology), should focus on what the change is about.

  • Include a link to the relevant documentation. Almost any release note should contain a link. If the description mentions a flag, a feature, a command name, users will probably want to know more about it.

  • Use backquotes around code, symbols, flags, or any word containing an underscore.

  • Do not just copy and paste bug descriptions. They are often cryptic and only make sense to us and leave the user scratching their head. Release notes are meant to explain what has changed and why in user-understandable language.

  • Always use present tense and the format “Bazel now supports Y” or “X now does Z.” We don’t want our release notes to sound like bug entries. All release note entries should be informative and use a consistent style and language.

  • If something has been deprecated or removed, use “X has been deprecated” or “X has been removed.” Not “is removed” or “was removed.”

  • If Bazel now does something differently, use “X now $newBehavior instead of $oldBehavior” in present tense. This lets the user know in detail what to expect when they use the new release.

  • If Bazel now supports or no longer supports something, use “Bazel now supports / no longer supports X”.

  • Explain why something has been removed / deprecated / changed. One sentence is enough but we want the user to be able to evaluate impact on their builds.

  • Do NOT make any promises about future functionality. Avoid “this flag will be removed” or “this will be changed.” It introduces uncertainty. The first thing the user will wonder is “when?” and we don’t want them to start worrying about their current builds breaking at some unknown time.

Process

As part of the release process, we collect the RELNOTES tags of every commit. We copy everything in a Google Doc where we review, edit, and organize the notes.

The release manager sends an email to the bazel-dev mailing-list. Bazel contributors are invited to contribute to the document and make sure their changes are correctly reflected in the announcement.

Later, the announcement will be submitted to the Bazel blog, using the bazel-blog repository.