Docs: Add introductions to Bazel pages
PiperOrigin-RevId: 348866891
diff --git a/site/docs/rule-challenges.md b/site/docs/rule-challenges.md
index 429e58b..f2d7ad5 100644
--- a/site/docs/rule-challenges.md
+++ b/site/docs/rule-challenges.md
@@ -5,11 +5,8 @@
# Challenges of Writing Rules
-We have heard feedback from various people that they have
-difficulty to write efficient Bazel rules. There is no single root cause, but
-it's due to a combination of historical circumstances and intrinsic complexity
-in the problem domain. This document attempts to give a high level overview of
-the specific issues that we believe to be the main contributors.
+This page gives a high-level overview of the specific issues and challenges
+of writing efficient Bazel rules.
* Assumption: Aim for Correctness, Throughput, Ease of Use & Latency
* Assumption: Large Scale Repositories
diff --git a/site/docs/rules.md b/site/docs/rules.md
index 921520d..68fa262 100644
--- a/site/docs/rules.md
+++ b/site/docs/rules.md
@@ -5,10 +5,12 @@
# Rules
-The Bazel ecosystem has a growing and evolving set of rules to support popular languages
-and packages. Much of Bazel's strength comes from the ability to
+The Bazel ecosystem has a growing and evolving set of rules to support popular
+languages and packages. Much of Bazel's strength comes from the ability to
[define new rules](skylark/concepts.html) that can be used by others.
+This page describes the recommended, native, and non-native Bazel rules.
+
## Recommended rules
Here is a selection of recommended rules:
diff --git a/site/docs/updating-bazel.md b/site/docs/updating-bazel.md
index 517caac..19fc0ce 100644
--- a/site/docs/updating-bazel.md
+++ b/site/docs/updating-bazel.md
@@ -5,13 +5,15 @@
# Updating Bazel
+This page covers how to automatically update your Bazel version using Bazelisk.
+
The Bazel project has a [backward compatibility
policy](https://docs.bazel.build/versions/master/backward-compatibility.html)
(see [guidance for rolling out incompatible
-changes](https://www.bazel.build/maintaining/breaking-changes-guide.html) if you are the
-author of one). That page summarizes best practices on how to test and migrate
-your project with upcoming incompatible changes and how to provide feedback to
-the incompatible change authors.
+changes](https://www.bazel.build/maintaining/breaking-changes-guide.html) if you
+are the author of one). That page summarizes best practices on how to test and
+migrate your project with upcoming incompatible changes and how to provide
+feedback to the incompatible change authors.
## Managing Bazel versions with Bazelisk
@@ -35,7 +37,6 @@
We recommend the following process for project migration:
-
1. Assume that your project already works with a given Bazel release, say 0.26,
and you want to prepare for the next release, say 0.27
2. Find all incompatible changes for which the migration can be started: they are marked with
diff --git a/site/docs/user-manual.html b/site/docs/user-manual.html
index a2b4624..35c878d 100644
--- a/site/docs/user-manual.html
+++ b/site/docs/user-manual.html
@@ -4,6 +4,10 @@
---
<h1>Commands and options</h1>
+This page covers the options that are available with various Bazel commands,
+such a `bazel build`, `bazel run`, and `bazel test`. This page is a companion
+to the <a href="https://docs.bazel.build/versions/master/guide.html">Bazel user guide</a>,
+which lists Bazel's commands.
<h2 id='target-patterns'>Target syntax</h2>
Some commands, like <code>build</code> or <code>test</code>, can operate
