docs: Reformat CI/CQ Intro
Bug: b/302680656
Change-Id: I4f9beb44755a7ea84889029f012a4b07f16401f2
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/174870
Reviewed-by: Kayce Basques <kayce@google.com>
Commit-Queue: Auto-Submit <auto-submit@pigweed-service-accounts.iam.gserviceaccount.com>
Pigweed-Auto-Submit: Rob Mohr <mohrr@google.com>
diff --git a/docs/infra/ci_cq_intro.rst b/docs/infra/ci_cq_intro.rst
index 30fc7bb..a501f21 100644
--- a/docs/infra/ci_cq_intro.rst
+++ b/docs/infra/ci_cq_intro.rst
@@ -9,78 +9,92 @@
----------
Essentials
----------
-**Submitting CLs**
- The Gerrit ``Submit`` button is hidden, replaced by the ``Submit to CQ``
- button. The ``Submit`` button is still accessible behind the ``...`` button
- in the top right corner of the Gerrit UI, but in some cases requires elevated
- permissions.
-**Triggering Presubmits**
- Presubmits are not automatically run when a patch set is uploaded. Click
- ``CQ Dry Run`` to trigger them. (You can also use
- ``git push origin +HEAD:refs/for/main%l=Commit-Queue``).
+Submitting CLs
+==============
+The Gerrit ``Submit`` button is hidden, replaced by the ``Submit to CQ``
+button. The ``Submit`` button is still accessible behind the ``...`` button
+in the top right corner of the Gerrit UI, but in some cases requires elevated
+permissions.
-**Presubmit Validity Duration**
- If you don't have recent passing results from a ``CQ Dry Run`` (within 24
- hours) then ``Submit to CQ`` will run presubmits. After any newly run
- presubmits pass this will submit the change.
+Triggering presubmits
+=====================
+Presubmits are not automatically run when a patch set is uploaded. Click
+``CQ Dry Run`` to trigger them. (You can also use
+``git push origin +HEAD:refs/for/main%l=Commit-Queue``).
-**User Interface**
- If a presubmit fails you'll get a Gerrit comment with a link to the failing
- build. The status of tryjobs (pending, running, failed, passed, etc.) is
- shown directly in the Gerrit UI (see :ref:`tryjobs`).
+Presubmit validity duration
+===========================
+If you don't have recent passing results from a ``CQ Dry Run`` (within 24
+hours) then ``Submit to CQ`` will run presubmits. After any newly run
+presubmits pass this will submit the change.
-**Auto-Submit**
- If you want your change to be automatically submitted when all requirements
- are met (``Code-Review +2``, ``OWNERS``-approval, all comments resolved,
- etc.) set the ``Auto-Submit`` label to +1.
+User interface
+==============
+If a presubmit fails you'll get a Gerrit comment with a link to the failing
+build. The status of tryjobs (pending, running, failed, passed, etc.) is
+shown directly in the Gerrit UI (see :ref:`tryjobs`).
+
+Auto-Submit
+===========
+If you want your change to be automatically submitted when all requirements
+are met (``Code-Review +2``, ``OWNERS``-approval, all comments resolved,
+etc.) set the ``Auto-Submit`` label to +1.
.. _further-details:
---------------
Further Details
---------------
-**Applying Changes in Testing**
- Changes are always rebased on the most recent commit when tested. If they
- fail to rebase the build fails.
- ``CQ Dry Run`` is the same as voting ``Commit-Queue +1`` label and
- ``Submit to CQ`` is the same as voting ``Commit-Queue +2``. If you vote both
- ``Code-Review +2`` and ``Commit-Queue +2`` on somebody's change you are
- submitting it for them.
-**Post-Submit Builders**
- Jobs are run post-submission too and can be seen at
- https://ci.chromium.org/p/pigweed (for public projects) and
- https://ci.chromium.org/p/pigweed-internal (for internal projects).
+Applying changes in testing
+===========================
+Changes are always rebased on the most recent commit when tested. If they
+fail to rebase the build fails.
+``CQ Dry Run`` is the same as voting ``Commit-Queue +1`` label and
+``Submit to CQ`` is the same as voting ``Commit-Queue +2``. If you vote both
+``Code-Review +2`` and ``Commit-Queue +2`` on somebody's change you are
+submitting it for them.
-**Auto-Submit**
- You can vote ``Pigweed-Auto-Submit +1`` (perhaps with a slightly different
- label name on different Gerrit hosts) and within a few minutes of
- getting the required code reviews your change will automatically be
- submitted. If this submission fails it will be retried a couple times with
- backoff and then the auto submit job will give up.
+Post-Submit builders
+====================
+Jobs are run post-submission too and can be seen at
+https://ci.chromium.org/p/pigweed (for public projects) and
+https://ci.chromium.org/p/pigweed-internal (for internal projects).
-**Non-main Branches**
- CQ is enabled for all branches. If you upload to an individual repository
- branch X and the manifest or superproject also has a branch X, that branch of
- the manifest will be used.
+Auto-Submit
+===========
+You can vote ``Pigweed-Auto-Submit +1`` (perhaps with a slightly different
+label name on different Gerrit hosts) and within a few minutes of
+getting the required code reviews your change will automatically be
+submitted. If this submission fails it will be retried a couple times with
+backoff and then the auto submit job will give up.
-**Rollers**
- Just because a change has been submitted doesn't mean it's live in the
- project. Submodules and Android Repo Tool projects often need to be
- `rolled (internal-only link) <http://go/pw-rollers>`_ before they're in the
- most recent checkout of the project.
+Non-``main`` branches
+=====================
+CQ is enabled for all branches. If you upload to an individual repository
+branch X and the manifest or superproject also has a branch X, that branch of
+the manifest will be used.
-**Presubmit Result**
- The ``Presubmit-Verified`` label is set at the completion of CQ runs. It does
- not block submission, but can be used by Copybara to see if CQ has passed.
- If it looks incorrect, do another CQ run and it will be updated.
+Rollers
+=======
+Just because a change has been submitted doesn't mean it's live in the
+project. Submodules and Android Repo Tool projects often need to be
+`rolled (internal-only link) <http://go/pw-rollers>`_ before they're in the
+most recent checkout of the project.
-**List of Builders**
- All builders can be viewed from Pigweed's "Builder Viz":
+Presubmit result
+================
+The ``Presubmit-Verified`` label is set at the completion of CQ runs. It does
+not block submission, but can be used by Copybara to see if CQ has passed.
+If it looks incorrect, do another CQ run and it will be updated.
- * `Builder Viz link for external contributors <https://pigweed.googlesource.com/infra/config/+/main/generated/pigweed/for_review_only/viz/index.md>`_
- * `Builder Viz link for Googlers <https://pigweed-internal.googlesource.com/infra/config/+/main/generated/pigweed/for_review_only/viz/index.md>`_
+List of builders
+================
+All builders can be viewed from Pigweed's "Builder Viz":
+
+ * `Builder Viz link for external contributors <https://pigweed.googlesource.com/infra/config/+/main/generated/pigweed/for_review_only/viz/index.md>`_
+ * `Builder Viz link for Googlers <https://pigweed-internal.googlesource.com/infra/config/+/main/generated/pigweed/for_review_only/viz/index.md>`_
.. _tryjobs:
@@ -124,7 +138,7 @@
`Chromium's depot tools <https://chromium.googlesource.com/chromium/tools/depot_tools.git>_`.
-Querying Tryjobs
+Querying tryjobs
----------------
In addition to viewing tryjobs in the Gerrit UI, you can use the ``bb`` command
to query the tryjobs that ran on a change. The command to use is
@@ -149,7 +163,7 @@
To exclude non-experimental tryjobs, add ``-t cq_experimental:false`` to the
command.
-Manually Launching Tryjobs
+Manually launching tryjobs
--------------------------
In most cases, individual tryjobs can be launched using
``Choose Additional Tryjobs``. If any relevant tryjobs are not listed here
@@ -188,7 +202,7 @@
.. _dependent-changes:
-----------------
-Dependent Changes
+Dependent changes
-----------------
.. _creating:
@@ -308,7 +322,7 @@
.. _banned-codewords:
-Banned Codewords
+Banned codewords
================
Sometimes the name of an internal Gerrit instance is a codeword we don't allow
on the Pigweed Gerrit instance. For example, you may wish to do the following.
