build: add documentation for running benchmarks

devversion · devversion · commit 9a01ac3f49f4 · 2023-06-19T14:10:31.000+02:00
Adds documentation for running benchmarks.
diff --git a/docs/BENCHMARKS.md b/docs/BENCHMARKS.md
@@ -0,0 +1,35 @@
+## Benchmarks
+
+- Benchmarks code can be found in: `/modules/benchmarks/src`.
+- Benchmarks convenience script code in `/scripts/benchmarks`.
+- Benchpress (the sample runner) in `/packages/benchpress`.
+
+### Running benchmark
+
+```
+yarn benchmarks run
+```
+
+### Running a comparison with local changes
+
+```
+yarn benchmarks run-compare main
+yarn benchmarks run-compare <compare-sha> [bazel-target]
+```
+
+If no benchmark target is specified, a prompt will allow you to select an available benchmark.
+
+### Running a comparison in a PR
+
+You can start a comparison by adding a comment as followed to any PR:
+
+```
+/benchmark-compare main //modules/benchmarks/src/expanding_rows:perf_chromium
+```
+
+```
+/benchmark-compare <other-sha> //modules/benchmarks/src/expanding_rows:perf_chromium
+```
+
+**Note**: An explicit benchmark target must be provided. You can use the prompt of `yarn benchmarks run` to
+discover available benchmarks.
diff --git a/scripts/benchmarks/README.md b/scripts/benchmarks/README.md
@@ -0,0 +1,11 @@
+## Benchmarks script
+
+This folder contains a convenience script for running benchmarks and performing comparisons. It can
+be run via `yarn benchmarks`. See command line help for possible commands.
+
+The benchmark script is used in conjunction with the benchmark compare GitHub actions workflow, allowing
+organization members to initiate a benchmark comparison via a GitHub comment in a PR.
+
+### Docs
+
+See ![the benchmark documentation](../../docs/BENCHMARKS.md).
