# HG changeset patch
# User Raphaël Gomès <rgomes@octobus.net>
# Date 1701335308 18000
#      Thu Nov 30 04:08:28 2023 -0500
# Node ID 47fb6cf117c0a932e02d1020f29313448144e856
# Parent  c998a787886912425dc90d982dd5fe8dd5fa28d3
# EXP-Topic docs
Update the benchmarks docs

diff --git a/docs/benchmarks.rst b/docs/benchmarks.rst
--- a/docs/benchmarks.rst
+++ b/docs/benchmarks.rst
@@ -2,16 +2,16 @@
 Details on benchmarks in Poulpe
 ===============================
 
-A benchmark describe "something" we want to get performance data on. It is
-defined in a "poulpe-benchmark-definition" file (`.pbd`). It will use code that
-exists in a poulpe's "binary-environment" to benchmark that "something" on the
-data present in a  poulpe's "binary-environment".
+A benchmark describes "something" we want to get performance information about.
+It is defined in a "poulpe-benchmark-definition" file (`.pbd`).
+It will use code that exists in a binary-environment to benchmark
+that "something" on the data present in a data-environment.
 
-The `.pbd` files includes multiple metadata and definition. Some are common to
-all type of benchmarks, some are specific to each type of benchmarks.
+The `.pbd` files include multiple kinds of metadata and definitions.
+Some are common to all types of benchmarks, some are specific.
 
-Generic metata data
-===================
+Generic metadata data
+=====================
 
 section: "meta"
 ---------------
@@ -19,22 +19,22 @@
 format
 ~~~~~~
 
-The version of this benchmark definition. Currently known version  are:
+The version of this benchmark definition. Currently known versions are:
 
 :0: The very first, quite volatile, version.
 
 name
 ~~~~
 
-identifier of the benchmark. This will be stored in result.
+identifier of the benchmark. This will be stored in results.
 
 method
 ~~~~~~
 
 The way this benchmark is expected to be run. It will also define most of the
-other value we expect to find to configure this benchmark.
+other values we expect to find to configure this benchmark.
 
-The current list of supported method is :
+The current list of supported methods is:
 
 :simple-command: benchmarking the run of a single shell command.
 :mercurial-perf-extension: using Mercurial perf extensions to run benchmarks
@@ -51,9 +51,9 @@
 section: environment
 --------------------
 
-A section that allow to set environment variable to be used when running the
-command. This is useful to replace some of the command argument with. Each
-sub-key is a an environment variable to replace.
+A section that allows to set environment variables to be used when running the
+command. This is useful to replace some of the command's arguments with. Each
+sub-key is an environment variable to replace.
 
 Value supports the `DATA-VARS:` notation if necessary
 
@@ -68,14 +68,14 @@
 
 The command to be run.
 
-It can we extended with variants (see next section)
+It can be extended with variants (see next section)
 
 cwd
 ~~~
 
-The directory to run the command in.
+The directory in which to run the command.
 
-Value can be substituded for data-env variable using the
+Values can be substituted for data-env variables using the
 `"DATA-VARS:path.to.variable.in.the.data.env"` syntax.
 
 For example `"DATA-VARS:mercurial.status.large.all"`
@@ -87,15 +87,18 @@
 prepare-run
 ~~~~~~~~~~~
 
-A command (or series of command) to run before each command run.
+A command (or series of commands) to run before each command run.
+
+Note: this command will be run with bash and prefixed with `set -eEuo pipefail`.
+You can opt out of the prefix by specifying "simple-command.no-set-builtin=true"
 
 variants
 --------
 
-Variants allow for slight variation of a benchmark. For example, they allow to change the
-input data, of to turn some feature on and off.
+Variants allow for slight variations of a benchmark. For example,
+they allow for changing the input data, or for turning some feature on and off.
 
-Variants are organised within independant "dimensions".
+Variants are organized within independent "dimensions".
 
 Each dimension has a set of values, each value can modify the benchmark. Each
 dimension must have a default value.
@@ -107,7 +110,7 @@
 
   simple-command.variants.dimensions.<dimension-name>.<variant-key>
 
-The `dimension-name` and `variant-key` are used as identifier in the benchmark
+The `dimension-name` and `variant-key` are used as identifiers in the benchmark
 result and for selecting variant at run time.
 
 variants variables
@@ -118,21 +121,21 @@
 
 Exactly one variant must have it set to `true` per dimension.
 
-When set and no variant have been explicitly selected for this dimension, this
-variant will be used.
+When set and no variant has been explicitly selected for this dimension during
+a benchmark run, this variant will be used.
 
 extend-command
 ~~~~~~~~~~~~~~
 
-A string to append to the commend when this variable is selected.
+A string to append to the command when this variable is selected.
 
 cwd
 ~~~
 
-overwrite the global `simple-command.cwd` variable. Behave the same.
+overwrites the global `simple-command.cwd` variable. Behaves the same.
 
-Mercurial perf extensions configuration
-=======================================
+Mercurial perf extension configuration
+======================================
 
 section: "hg-perf-ext"
 ----------------------
@@ -151,37 +154,40 @@
 args
 ~~~~
 
-Arguments to pass to the command (a list of string).
+Arguments to pass to the command (a list of strings).
 
 setup-script
 ~~~~~~~~~~~~
 
-a shell script to run before running the perf-command.
+A shell script to run before running the perf-command.
+
+Note: this command will be run with bash and prefixed with `set -eEuo pipefail`.
+You can opt out of the prefix by specifying "hg-perf-ext.no-set-builtin=true"
 
 constraints
 ~~~~~~~~~~~
 
-Theses variables control when this benchmark can be run.
+These variables control when this benchmark can be run.
 
 Here is the list of currently supported constraints:
 
 - `graph.visible-revision-count.min=<integer>`:
 
-  Target repository must have at least that many visible revision for this
+  Target repository must have at least that many visible revisions for this
   benchmark to run.
 
 - `compatible-revision-range=<revset>`:
 
-  The range of revision compatible with this changes. 
+  The range of revisions compatible with the command being run.
 
 
 variants
 --------
 
-Variants allow for slight variation of a benchmark. For example, they allow to change the
-input data, of to turn some feature on and off.
+Variants allow for slight variations of a benchmark. For example,
+they allow for changing the input data, of for turning some feature on and off.
 
-Variants are organised within independant "dimensions".
+Variants are organized within independent "dimensions".
 
 Each dimension has a set of values, each value can modify the benchmark. Each
 dimension must have a default value.
@@ -189,12 +195,12 @@
 defining a variant
 ~~~~~~~~~~~~~~~~~~
 
-Variants are defined under keys following this patterns :
+Variants are defined under keys following this pattern:
 
   hg-perf-ext.variants.dimensions.<dimension-name>.<variant-key>
 
-The `dimension-name` and `variant-key` are used as identifier in the benchmark
-result and for selecting variant at run time.
+The `dimension-name` and `variant-key` are used as identifiers in the benchmark
+result and for selecting variants at run time.
 
 variants variables
 ~~~~~~~~~~~~~~~~~~
@@ -204,20 +210,20 @@
 
 Exactly one variant must have it set to `true` per dimension.
 
-When set and no variant have been explicitly selected for this dimension, this
+When set and no variant has been explicitly selected for this dimension, this
 variant will be used.
 
 args
-~~~~~~~~~~~~~~
+~~~~
 
 A list of args to add to the command
 
 cwd
 ~~~
 
-overwrite the global `hg-perf-ext.cwd` variable. Behave the same.
+Overwrites the global `hg-perf-ext.cwd` variable. Behaves the same.
 
 setup-script
 ~~~~~~~~~~~~
 
-overwrite the global `hg-perf-ext.setup-script` variable. Behave the same.
+Overwrites the global `hg-perf-ext.setup-script` variable. Behaves the same.