Docs: Rewrite Bazel pages for intended user: Skylark, part 6
PiperOrigin-RevId: 369886737
diff --git a/site/docs/skylark/aspects.md b/site/docs/skylark/aspects.md
index 29c0b73..a47e432 100644
--- a/site/docs/skylark/aspects.md
+++ b/site/docs/skylark/aspects.md
@@ -256,11 +256,11 @@
)
```
-In this example, we are again propagating the aspect via the ``deps`` attribute.
+This example shows how the aspect propagates through the ``deps`` attribute.
``attrs`` defines a set of attributes for an aspect. Public aspect attributes
are of type ``string`` and are called parameters. Parameters must have a``values``
-attribute specified on them. In this case we have a parameter called ``extension``
+attribute specified on them. This example has a parameter called ``extension``
that is allowed to have '``*``', '``h``', or '``cc``' as a value.
Parameter values for the aspect are taken from the string attribute with the same
@@ -325,7 +325,7 @@
applied and cannot be modified from an aspect.
The parameters and private attributes are passed in the attributes of the
-``ctx``. In this example, we reference the ``extension`` parameter to decide
+``ctx``. This example references the ``extension`` parameter and determines
what files to count.
For returning providers, the values of attributes along which
diff --git a/site/docs/skylark/build-style.md b/site/docs/skylark/build-style.md
index f2b91bd..860495e 100644
--- a/site/docs/skylark/build-style.md
+++ b/site/docs/skylark/build-style.md
@@ -6,8 +6,8 @@
# BUILD Style Guide
-In `BUILD` files, we take the same approach as in Go: We let the machine take care
-of most formatting issues.
+`BUILD` file formatting follows the same approach as Go, where a standardized
+tool takes care of most formatting issues.
[Buildifier](https://github.com/bazelbuild/buildifier) is a tool that parses and
emits the source code in a standard style. Every `BUILD` file is therefore
formatted in the same automated way, which makes formatting a non-issue during
@@ -44,7 +44,7 @@
## File structure
-We recommend to use the following order (every element is optional):
+**Recommendation**: Use the following order (every element is optional):
* Package description (a comment)
@@ -57,7 +57,7 @@
Buildifier makes a distinction between a standalone comment and a comment
attached to an element. If a comment is not attached to a specific element, use
an empty line after it. The distinction is important when doing automated
-changes (e.g. to decide if we keep or remove a comment when we delete a rule).
+changes (for example, to keep or remove a comment when deleting a rule).
```python
# Standalone comment (e.g. to make a section in a file)
@@ -179,8 +179,8 @@
directory with a dependency graph defined between them as this enables better
remote caching and parallelism.
-We recommend authoring a BUILD file per directory and defining a dependency
-graph between them instead.
+It is good practice to author a BUILD file in each directory and define a
+dependency graph between them.
### Non-recursive
@@ -225,8 +225,7 @@
* Use spaces around the `=` sign for keywords arguments in rules. *Rationale*:
Named arguments are much more frequent than in Python and are always on a
separate line. Spaces improve readability. This convention has been around
- for a long time, and we don't think it is worth modifying all existing
- `BUILD` files.
+ for a long time, and it is not worth modifying all existing `BUILD` files.
* By default, use double quotation marks for strings. *Rationale*: This is not
specified in the Python style guide, but it recommends consistency. So we
diff --git a/site/docs/skylark/bzl-style.md b/site/docs/skylark/bzl-style.md
index 402af53..65ae2a6 100644
--- a/site/docs/skylark/bzl-style.md
+++ b/site/docs/skylark/bzl-style.md
@@ -55,8 +55,7 @@
When in doubt, follow the
[PEP 8 style guide](https://www.python.org/dev/peps/pep-0008/). In particular,
-use 4 spaces for indentation (we previously recommended 2, but we now follow the
-Python convention).
+use four rather than two spaces for indentation to follow the Python convention.
### Docstring
diff --git a/site/docs/skylark/concepts.md b/site/docs/skylark/concepts.md
index 83f8154..ad33856 100644
--- a/site/docs/skylark/concepts.md
+++ b/site/docs/skylark/concepts.md
@@ -14,7 +14,7 @@
Bazel extensions are files ending in `.bzl`. Use a [load statement](
../build-ref.html#load) to import a symbol from an extension.
-Before learning the more advanced concepts, we recommend that you first:
+Before learning the more advanced concepts, first:
* Read about the [Starlark language](language.md), used in both the BUILD and
`.bzl` files.
@@ -37,15 +37,15 @@
If you want to reuse simple logic, start with a macro. If a macro becomes
complex, it is often a good idea to make it a rule. Support for a new language
-is typically done with a rule. Rules are for advanced users: we expect that most
-people will never have to write one, they will only load and call existing
+is typically done with a rule. Rules are for advanced users, and most
+users will never have to write one; they will only load and call existing
rules.
## Evaluation model
A build consists of three phases.
-* **Loading phase**. First, we load and evaluate all extensions and all BUILD
+* **Loading phase**. First, load and evaluate all extensions and all BUILD
files that are needed for the build. The execution of the BUILD files simply
instantiates rules (each time a rule is called, it gets added to a graph).
This is where macros are evaluated.
@@ -53,10 +53,9 @@
* **Analysis phase**. The code of the rules is executed (their `implementation`
function), and actions are instantiated. An action describes how to generate
a set of outputs from a set of inputs, e.g. "run gcc on hello.c and get
- hello.o". It is important to note that we have to list explicitly which
- files will be generated before executing the actual commands. In other words,
- the analysis phase takes the graph generated by the loading phase and
- generates an action graph.
+ hello.o". You must list explicitly which files will be generated before
+ executing the actual commands. In other words, the analysis phase takes
+ the graph generated by the loading phase and generates an action graph.
* **Execution phase**. Actions are executed, when at least one of their outputs is
required. If a file is missing or if a command fails to generate one output,
@@ -70,7 +69,7 @@
Bazel tries to be clever: it uses dependency analysis to know which files must
be loaded, which rules must be analyzed, and which actions must be executed. For
-example, if a rule generates actions that we don't need for the current build,
+example, if a rule generates actions that you don't need for the current build,
they will not be executed.
## Creating extensions
@@ -94,8 +93,8 @@
In addition to [macro](macros.md) and [rules](rules.md), you may want to write
[aspects](aspects.md) and [repository rules](repository_rules.md).
-* Use [Buildifier](https://github.com/bazelbuild/buildtools) to format and lint
- your code. We recommend that you use it consistently.
+* Use [Buildifier](https://github.com/bazelbuild/buildtools) consistently to
+format and lint your code.
* Follow the [`.bzl` style guide](bzl-style.md).
diff --git a/site/docs/skylark/config.md b/site/docs/skylark/config.md
index ff4f920..bb6b908 100644
--- a/site/docs/skylark/config.md
+++ b/site/docs/skylark/config.md
@@ -394,8 +394,8 @@
A configuration
[transition](lib/transition.html#transition)
-is how we change configuration of
-configured targets in the build graph.
+maps the transformation from one configured target to another within the
+build graph.
> IMPORTANT: Transitions have [memory and performance impact](#memory-and-performance-considerations).
> Rules that set them must include a special attribute:
@@ -510,7 +510,7 @@
NOTE: There is currently no way to attach Starlark transitions to native rules.
If you need to do this, contact
bazel-discuss@googlegroups.com
-and we can help you try to figure out a workaround.
+for help with figuring out workarounds.
### Incoming edge transitions
Incoming edge transitions are activated by attaching a `transition` object
@@ -545,10 +545,10 @@
[End to end example](https://github.com/bazelbuild/examples/tree/master/rules/starlark_configurations/transition_on_native_flag)
-WARNING: Long term, we plan to reimplement all native options as build settings.
-When that happens, this syntax will be deprecated. Currently other issues are
-blocking that migration but be aware you may have to migrate your transitions
-at some point in the future.
+WARNING: Long term, the plan is to reimplement all native options as build
+settings. When that happens, this syntax will be deprecated. Currently other
+issues are blocking that migration but be aware you may have to migrate your
+transitions at some point in the future.
Starlark transitions can also declare reads and writes on native build
configuration options via a special prefix to the option name.
