bazelbuild / proposals

Index of all Bazel proposals and design documents

Bazel Documents

This is an index of all documents for Bazel.

There are two kinds:

• Design docs that are subject to the workflow described below
• Live documents for which the workflow is not a good fit

Design doc workflow

New proposals follow the design process and are sent for review as a GitHub discussion.

State diagram of the design process

stateDiagram-v2    
    ur: Under review
    
    Draft --> ur
    ur --> Approved
    Approved --> Implemented
    Draft --> Dropped
    ur --> Dropped
    Approved --> Dropped
    
    classDef success fill:#ded
    classDef failure fill:#fcc
    
    class Implemented success
    class Dropped failure

Live documents

Last updated	Title	Author(s) alias
2023-10-09	Starlark Rules Roadmap	@comius
2023-09-26	Bazelbuild Repositories Maintenance Guide	@comius and @meteorcloudy
2023-08-30	Bazel Proto Rules	@comius
2023-08-01	Problems with Bazel's code coverage collection	@c-mita
2023-07-27	A Guide to Skyframe StateMachines	@aoeui
2022-02-17	The Bazel codebase	@lberki

Design docs

Under review

Last updated	Title	Author(s) alias	Category
2024-03-18	A new home for the host platform	@Wyverald	Configurability, External Repositories
2024-02-10	Execution Platform Scoped Spawn Strategies	@Silic0nS0ldier	Configurability, Execution Strategy
2024-02-06	Linking on multiple platforms	@comius	C++ linking
2024-01-22	Garbage collection for the disk cache	@tjgq	Performance
2024-01-18	Bazel Remote Output Service	@coeuvre	Remote Execution
2023-12-12	--remote_local_fallback Respects Strategy Declarations	@Silic0nS0ldier	Configurability, Execution Strategy
2023-12-5	Offline & Vendor Modes	@salmasamy	Bazel, External Repositories
2023-11-09	Avoiding accidental secret leaks in the BEP	@jmmv	Core
2023-09-19	Bazel Ruleset GOVERNANCE | MECHANICS	@radvani13	Rules
2023-10-25	C++20 Modules Support	@PikachuHyA	C++
2023-09-12	Proto toolchainization	@comius	Protos
2023-09-07	A true repository cache	@Wyverald	External Repositories
2023-08-08	Standard exec configurations	@gregestren	Configurability
2023-08-08	Inheritance of Target Incompatibility	@fmeum	Platforms, Configurability
2023-06-30	Fingerprinting Starlark Functions	@brandjon	Starlark and actions
2023-06-16	Extending Bazel rules	@comius	Starlark Rules
2023-06-15	Integrated bzl_library	@brandjon	Starlark
2023-05-31	subrule: Decomposing Starlark rules	@comius	Starlark Rules
2023-03-17	C/C++ standard resolution for Bazel modules	@fmeum	C++, External Repositories
2023-03-17	More accurate cquery	@gregestren	Configurability
2022-10-17	Dependency adapters for virtual targets	@vdye	Bazel

Draft

Last updated	Title	Author(s) alias	Category
2023-11-23	Regular rules in module extensions	@matts1	External Repositories
2023-10-25	Faster aspects: pruning on the way down	@aiuto
2023-10-25	Better SBOMS: annotated rule attributes	@aiuto
2023-10-23	Incremental builds with small memory footprint	@lberki	Core
2023-01-18	Modular cc toolchains	@silvergasp	CC toolchain rules
2020-10-09	Adding http mirror to accelerate repos downloading	@yancl	External Repositories
2021-06-25	Better Starlark analysis unit tests	@hvadehra	Starlark
2022-04-25	Extend expand_template() API to reduce retained memory	@hvadehra	Starlark
2022-04-29	@since(version) annotations in documentation.	@aiuto	Documentation

Approved

Last updated	Title	Author(s) alias	Category
2024-05-24	Dormant Dependencies	@lberki	Build Language
2024-05-08	Selectively Enabling Execution Platforms	@katre	Configuration
2024-04-29	Starlark Transition Composition	@katre	Configuration
2023-12-06	bazel mod tidy	@fmeum	External dependencies
2023-08-14	Platform-based flags	@katre	Platforms
2023-08-08	Standard platform transitions	@katre	Platforms
2023-06-12	Remote Output Service: place bazel-out/ on a FUSE file system	@EdSchouten	Remote Execution
2023-03-21	Bazel feature detection in Starlark	@Wyverald	General, Starlark Rules
2023-03-14	REPO.bazel	@Wyverald	External Repositories
2023-03-07	Build Stamping API for Starlark rules	@buildbreaker2021	Starlark Rules
2023-01-23	Remote Cache Eviction for Build without the Bytes	@coeuvre	Remote Execution
2022-10-11	Renaming applicable_licenses	@aiuto	Configuration
2023-01-30	Transitive static libraries	@fmeum	C++
2022-12-15	Bzlmod lockfile	@salmasamy	Bazel, External Repositories
2022-05-12	Bzlmod External Dependencies Inspection Tool	@andyrinne12	External Repositories
2022-05-11	Deprecating managed_directories	@lberki	External Repositories
2021-02-15	External directory reshuffling	@lberki	External Repositories
2021-02-15	C++ rules skylark migration plan	@mhlopko	C++
2019-05-08	Android Native to Starlark Migration	@timpeut	Android
2018-08-14	Decoupling android_ndk_repository from Bazel	@jin	Android
2018-07-31	Splitting large BEP events	@buchgr	Build Event Protocol

Implemented

Last updated	Title	Author(s) alias	Category
2024-06-06	Simplifying lockfile maintenance	@fmeum	External Repositories
2023-05-04	Directory watching API for repo rules	@Wyverald	External Repositories
2022-09-05	Automatic exec groups for toolchains	@comius @kotlaja	Configurability
2023-03-20	Automatic use_repo fixups for module extensions	@fmeum	External Repositories
2022-08-17	Locating runfiles with Bzlmod	@fmeum	External Repositories, Bazel
2023-06-13	Credential Helpers for Bazel	@Yannic	External Repositories
2022-03-18	proto_common module	@comius	Proto Rules
2021-06-23	Improving native.existing_rules	@tetromino, @brandjon	Build Language
2021-06-09	Aspects Propagating other Aspects	@messa	Starlark
2021-04-22	Custom constructors for providers	@brandjon	Build Language
2021-03-24	Java common refactoring	@comius	Java rules
2020-12-22	Injecting Starlark Values Into Builtins	@brandjon	Starlark
2021-03-06	OSS License Declarations	@aiuto	Product
2021-02-15	Rules for software license compliance	@aiuto	License Rules, Bazel
2023-03-31	Optional Toolchains	@katre	Configurability
2022-05-25	Canonical label literals	@Wyverald	External Repositories
2022-03-07	Representing repeatable Starlark flags as config.string_list	@fmeum	Configurability, Build Language
2022-01-14	Proposal for subpackages built-in helper function	@kkress	Bazel
2021-08-02	Bazel Central Registry Policies and Procedures	@meteorcloudy	External Repositories
2021-03-06	Remote Persistent Workers	[@ulfjack]
2021-03-06	Rules authors SIG	@alexeagle	Community
2021-02-18	Require ProtoInfo for proto_lang_toolchain#blacklisted_protos	@Yannic	Protobuf
2021-02-16	Selecting Between Python 2 and 3	@brandjon	Python
2021-02-16	Remote Downloads	@EricBurnett, @jmillikin, @sstriker	External Repositories
2021-02-16	Starlark Directory Expansion in Args MapEach	@haileiyu	Starlark
2021-02-16	Test execution on Windows without Bash	@laszlocsomor	Windows
2021-02-15	Toolchain resolution using configuration flags	@comius	Configurability
2021-02-15	Configured Query Starlark Output	@c-parsons	Configurability, Starlark
2021-02-15	Proposal: new format ‘flag_per_line’ for Args	@vmaverick	Starlark
2021-02-15	cquery somepath: easy mode	@gregestren	Configurability
2021-02-15	Automatically migrating maven_jar to rules_jvm_external	@jin	External Repositories
2021-02-15	Target-level execution properties	@agoulti	Configurability
2021-02-15	Bazel Starlark API: add ctx.resolve_tools	@laszlocsomor	Starlark
2021-02-15	Auto-configured Host Platform	@katre	Configurability
2021-02-15	Multiplex persistent worker	@borkaehw	Bazel
2021-02-15	Starlark Build Configuration	@juliexxia, @gregestren	Configurability
2021-02-15	Crosstool in Skylark	@scentini, @mhlopko	C++
2021-02-15	Declared Providers	@dslomov, @laurentlb	Starlark
2021-02-15	Java Platformization	@comius	Configurability
2021-02-15	Starlark Shorthand Flag Mapping	@WarkahScott	Configurability
2021-02-15	Measuring Configuration Overhead	@gregestren	Configurability
2021-02-15	Action Groups (Multi-Toolchain Resolution)	@juliexxia	Configurability
2021-02-15	Common Bazel Constraints	@gregestren	Configurability
2021-02-15	Starlark Build Configurations - Parameterized-Transitions API	@juliexxia	Configurability
2021-02-15	Partial C++ Starlark API	@oquenchil	C++
2021-02-15	Crosstool in Skylark	@mhlopko	C++
2021-02-15	Shrinking the Bazel binary	@buchgr, @meistert	Bazel
2021-02-15	External C/C++ libraries rules	@ichern	Bazel
2021-02-15	Bazel Runfiles Libraries	@laszlocsomor	Bazel
2021-02-15	Name resolution	@laurentlb	Starlark
2020-10-28	Keepalived remote execution	@coeuvre	Remote Execution
2020-10-19	Bazel External Dependencies Overhaul	@meteorcloudy, @philwo, @Wyverald	External Repositories
2020-09-30	Toolchain Transition Migration	@katre	Configurability
2020-09-30	Toolchain Transitions	@katre	Configurability
2020-09-30	Passing Toolchain Context across Dependencies	@katre	Configurability
2020-05-13	Execution Transitions	@katre	Configurability
2020-05-13	Old Flags to Platform Migration	@aragos	Configurability
2019-12-20	Incompatible Target Skipping	@AustinSchuh, @gregestren	Configurability
2019-12-17	cquery somepath: easy mode	@gregestren	Configurability
2019-12-17	Exposing Target Platform Constraints	@katre	Configurability
2019-10-24	Visibility for source files	@aehlig	Build API
2019-04-22	Move //tools/build_defs/pkg to rules_pkg	@aiuto	Bazel
2019-05-10	Bazel with NPM package manager	@ichern	External Repositories
2019-05-27	Authentication for ctx.download	@aehlig	External Repositories
2019-04-29	Forcing non-cache-hits in the repository cache	@aehlig	External Repositories
2019-04-05	Handling download failures	@aehlig	External Repositories
2018-12-14	Versioned Documentation	@jin	Documentation
2018-11-26	Update Download Functions in repository_ctx	@dkelmer	External Repositories
2018-11-14	Platform Inheritance	@katre	Configurability
2018-11-09	Config Setting Chaining	@gregestren	Configurability
2018-10-29	Progress reporting for external repositories	@aehlig	External Repositories
2018-11-10	Symlinks in Remote Execution	@buchgr	Remote Execution
2018-08-27	Args Directory Support	@tomlu	Starlark
2018-08-20	Skylark API to the C++ toolchain	@mhlopko	C++
2018-08-03	Skyframe threading model	@tomlu	Skyframe
2018-07-13	Bazel hashing of external directory output	@aehlig	External Repositories
2018-05-24	Unified Configuration Transitions	@gregestren	Configurability
2018-04-26	Per-Rule Execution Platform Constraints	@katre	Configurability
2017-10-06	Dynamic Bazel Configurations	@gregestren	Configurability
2017-03-03	Label-keyed String Dictionary Type for Build Attributes	@serynth	Configurability
2017-01-20	Aspect required providers	@tomlu, @dslomov	Starlark
2017-01-20	Aspects-on-aspects	@dslomov	Starlark
2016-10-18	Invalidation of remote repositories	@damienmg	External Repositories
2016-10-11	Distribution Artifact for Bazel	@aehlig	Release
2016-09-30	Central cache for external repositories	@jin	External Repositories
2016-09-05	Building Python on Windows	@meteorcloudy	Python, Windows
2016-06-21	Specifying environment variables	@aehlig	Bazel
2016-06-02	Sandboxing	@philwo	Bazel
2016-05-26	Implementing Beautiful Error Messages (Loading Phase)	@laurentlb	Bazel
2016-05-23	Beautiful error messages	@laurentlb	Bazel
2016-04-18	Parameterized Skylark Aspects	@dslomov, lindleyf	Starlark
2016-02-16	Generating C++ crosstool with a Skylark Remote Repository	@damienmg	Toolchains
2015-07-02	Skylark Remote Repositories	@damienmg	External repositories

Dropped

Last updated	Title	Author(s) alias	Category
2023-06-21	Integrated bzl_library	@brandjon	Starlark
2022-02-18	Coding guidelines for Starlark rules	@comius	Starlark Rules
2019-07-11	Load Bazel Protobuf rules from @rules_proto	@Yannic	Protobuf
2022-07-07	Enabling Global exec_groups	@susinmotion	Configurability
2021-06-17	Starlark fail(errorcode="")	@aiuto	Documentation / Event Stream
2023-03-31	Execution Platforms vs. Strategies	@katre and @aragos	Configurability
2021-02-18	Toolchainifying proto rules	@Yannic	Protobuf
2023-03-30	Guidance for Rules Authors how to deal with Bazel versions / upgrades	@philwo	Bazel
2022-11-16	Platforms on Targets	@katre	Configuration
2021-07-21	Monorepo Toolchain Registration	@katre	Toolchains
2021-02-16	Semantics of the expansion of Labels	@aehlig	External Repositories
2021-02-16	Propagate tags from the targets to actions	@ishikhman	Bazel, Starlark
2021-02-16	Remote Repository Cache	jmillikin	External Repositories
2021-02-16	Moving Skylark out of Bazel	@brandjon	Starlark
2021-02-16	Dependency Discovery Proposal	@stevebillings	External Repositories
2021-02-16	s/skydoc/stardoc/g: a plan	@jin	Documentation
2021-02-16	Experimental Content-Based Output Paths	@gregestren	Configurability
2021-02-15	Managing Breaking Changes in Bazel	@dslomov	Community
2021-02-15	Separating Build API from Bazel	@c-parsons	Starlark
2021-02-15	Improved Command Line Reporting	@cvcal	Bazel
2021-02-15	Bazel External Dependencies Roadmap	@dslomov	External Repositories
2021-02-15	Aspects Propagating Other Aspects	@lberki	Build API
2021-02-15	Mandatory load() statements in BUILD files	@lberki	Starlark
2021-02-15	Visibility for implicit attributes	@aehlig	Build API
2021-02-15	Structured Compiler Diagnostics	@illicitonion	Build Event Protocol, Build API
2021-02-15	Replacing native <lang>_proto_library rules with Starlark	@Yannic	Protobuf
2021-02-15	Always dirty repository rules	@ichern	External Repositories
2021-02-15	Design for a Python Toolchain	@brandjon	Python
2021-02-15	Bazel Federation	@dslomov, @laurentlb	Community
2021-02-15	On custom shell toolchain for Bazel Starlark rules	@ichern	Toolchains, Starlark
2021-02-15	Recursive Workspaces	@aehlig	External Repositoires
2021-02-15	Resource auto-tuning via flags	@jmmv	Performance
2021-02-15	Repository Remapping Revisited	@dkelmer	External Repositories
2021-02-15	Bazel Rules Curation	@laurentlb	Community
2021-02-15	Extending the design of WORKSPACE files	@aehlig, @dslomov	External Repositories
2021-02-15	Namespaces when using multiple bazel repositories	@aehlig, @dslomov	External Repositories
2021-02-15	Delaying of load statements	@aehlig	External Repositories
2021-02-15	Repository rules with multiple return values	@aehlig	External Repositories
2021-02-15	Diamond Splitting for External Repositories	@dslomov	External Repositories
2021-02-15	Output Map Madness	@brandjon	Starlark
2021-02-15	External Repositories: The Future	@aehlig, @dslomov	External Repositories
2021-02-15	A Brave New World for the Bazel WORKSPACE File	@mattmoor, @dslomov, @davidstanke, @damienmg	External Repositories
2021-02-15	Garbage Collection for the Repository Cache	@aehlig	External Repositories
2021-02-15	Saner Skylark Sets	@dslomov	Starlark
2021-02-15	Customizing the Python Stub Template	@brandjon	Python
2021-02-15	HTTP downloads with Authorization using .netrc	@genrym	External Repositories
2021-02-15	Package Validation Proposal	@kkress	Bazel, Starlark
2020-10-19	Adding a constraint to default target platform	@comius	Configurability
2020-09-30	Bazel Constraint Equality	@aragos	Configurability
2020-09-30	Versioned Runtime APIs under Platforms & Toolchains	@aragos	Configurability
2020-01-16	Starlark project files	@robbertvanginkel	Bazel, Starlark
2019-08-22	Non-Hermetic Tool Paths in Platforms	@aragos	Configurability
2019-08-01	Platforms and Strategies	@katre	Configurability, Execution Strategy
2018-06-14	Platforms and Configurations	@katre	C++, Starlark
2016-09-19	Recursive WORKSPACE file parsing	@kchodorow	External Repositories
2015-03-06	bazel init a.k.a ./configure for Bazel	@damienmg	Bazel

proposals's Issues

Add subteams/OWNERS to aid with picking appropriate Design reviewers

See comment at bazelbuild/bazel-website#115 (comment)

"The Ideal Bazel Federation" isn't present in repo

Description

"The Ideal Bazel Federation" is a Bazel proposal mentioned here in a talk at Bazelcon 2019. I can't seem to find it here in the repo. Are you able to add it, please?

Use a structured file as source of truth, and generate markdown table from it

It's starting to get unwieldy to add or modify the table contents. @petroseskinder suggested that we can store the files in a YAML file, and generate the table using a script.

Reorder and reorganize the README for better utility

We can move "Implemented" and Dropped to a history index. The main view should show what is interesting. The priority for that is

1. What is under review
2. What is in draft

But why is Draft even there are all? Once you tell people about it, it is out for review, even if you don't think you want comments about it. If you want to share something with just a few people, you should do that via other channels.

template: Google Doc and Markdown Doc are currently inconsistent?

At time of writing, headers in Markdown doc (22a8b72):

• Abstract
• Background
• Proposal
• Backward-compatibility

Headers in Google doc:

• Overview
• Compatibility
• Document History

Dunno if it matters, but was a tad odd to see.

Categorize proposal list

I'd find it really useful to have a way to filter the proposal list by focus area.

For example, as one who focuses on configurability it's invaluable to be able to quickly and easily see all Configurability docs and even have them sub-indexed by configurability-specific areas like platforms, trimming, Starlark configuration, or output paths.

This would also support bringing new collaborators up to speed with these areas' work.

designs/2022-06-07-bazel-credential-helpers.md says request has "url", but bazel uses "uri"

https://github.com/bazelbuild/proposals/blob/main/designs/2022-06-07-bazel-credential-helpers.md

get: Retrieves credentials. The payload provided as standard input to the credential helper will be a json object with a single key url containing the url (including the protocol) to get credentials for ({"url": "..."}).

but
https://github.com/bazelbuild/bazel/blob/c00e8e623b717ecb734feeeb8f268af718b95683/src/main/java/com/google/devtools/build/lib/authandtls/credentialhelper/GetCredentialsRequest.java#L66

  writer.name("uri").value(value.getUri().toString());