Skip to content

Commit 9590d56

Browse files
committed
rephase build phase doc, clarify provider/rule definition
1 parent 572a352 commit 9590d56

File tree

1 file changed

+15
-11
lines changed

1 file changed

+15
-11
lines changed

CONTRIBUTING.md

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -193,17 +193,21 @@ Some miscellanous style, idioms, and conventions we have are:
193193
`x.test`. The `.` is our convention to communicate that it's a generated
194194
target, and thus one should look for `name="x"` when searching for the
195195
definition.
196-
* The different build phases and interface/implementation pieces of rules should
197-
be in different files. Stated another way: loading code for thing shouldn't
198-
incur loading code that isn't relevant.
199-
* Providers should be in their own files. This allows implementing a custom
200-
rule that implements the provider without loading an existing
201-
implementation.
202-
* The repository phase shouldn't `load()` code that is only relevant to the
203-
loading-phase or subsequent phases. Vice-versa, loading-phase code should
204-
not load any repository-phase code.
205-
* Generally, one rule per file. The goal is that defining an e.g. library
206-
shouldn't incur loading all the code for binaries, tests, packaging, etc.
196+
* The different build phases shouldn't load code that defines objects that
197+
aren't valid for their phase. e.g.
198+
* The bzlmod phase shouldn't load code defining regular rules or providers.
199+
* The repository phase shouldn't load code defining module extensions, regular
200+
rules, or providers.
201+
* The loading phase shouldn't load code defining module extensions or
202+
repository rules.
203+
* Loading utility libraries or generic code is OK, but should strive to load
204+
code that is usable for its phase. e.g. loading-phase code shouldn't
205+
load utility code that is predominately only usable to the bzlmod phase.
206+
* Providers should be in their own files. This allows implementing a custom rule
207+
that implements the provider without loading a specific implementation.
208+
* One rule per file is preferred, but not required. The goal is that defining an
209+
e.g. library shouldn't incur loading all the code for binaries, tests,
210+
packaging, etc; things that may be niche or uncommonly used.
207211
* Separate files should be used to expose public APIs. This ensures our public
208212
API is well defined and prevents accidentally exposing a package-private
209213
symbol as a public symbol.

0 commit comments

Comments
 (0)