pw_toolchain: Document conversion_warnings feature

Bug: 259746255
Change-Id: I296784dba145455382995153b314bc156431440a
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/276892
Reviewed-by: Wyatt Hepler <hepler@google.com>
Lint: Lint 🤖 <android-build-ayeaye@system.gserviceaccount.com>
Commit-Queue: Ted Pudlik <tpudlik@google.com>

Author: tpudlik

pw_toolchain/bazel.rst

@@ -168,6 +168,48 @@ To integrate Pigweed's toolchain with `bazel_clang_tidy
 Now ``bazelisk build --config=clang-tidy //...`` will run clang-tidy for all
 ``cc_library`` targets in your repo!
 
+Conversion warnings
+===================
+By default, upstream Pigweed is built with `-Wconversion
+<https://clang.llvm.org/docs/DiagnosticsReference.html#wconversion>`__ enabled.
+However, this was not always the case, and many Pigweed targets contain
+``-Wconversion`` violations. (:bug:`259746255` tracks fixing all of these.)
+
+Upstream allowlist
+------------------
+Do not add new ``-Wconversion`` violations to the Pigweed codebase.
+
+If you write new code that fails to build because it includes a header with a
+pre-existing ``-Wconversion`` violation, try to fix the pre-existing violation.
+
+As a last resort, you may add the ``features = ["-conversion_warnings"]`` (note
+the ``-``!) attribute to your ``cc_library`` or other build target:
+
+.. code-block:: py
+
+   cc_library(
+      name = "…",
+      features = ["-conversion_warnings"],
+   )
+
+This will disable ``-Wconversion`` for this target.
+
+Downstream use
+--------------
+If you would like to enable ``-Wconversion`` in a downstream project that uses
+Pigweed's toolchains, add a `REPO.bazel
+<https://bazel.build/external/overview#repo.bazel>`__ file at the root of
+your project, with the following content:
+
+.. code-block:: py
+
+   repo(
+       features = ["conversion_warnings"],
+   )
+
+This will enable ``-Wconversion`` for all code in your project, but not for
+code coming from any external dependencies also built with Bazel.
+
 .. _module-pw_toolchain-bazel-compiler-specific-logic:
 
 -----------------------------