Markdown linter (#1309)

* Add markdown linting - add linter default rules - adapt rules to current code - fix the code for linting to pass - add CI check fix #1243 * Fix markdown for Substrate * Fix tooling install * Fix workflow * Add documentation * Remove trailing spaces * Update .github/.markdownlint.yaml Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io> * Fix mangled markdown/lists * Fix captalization issues on known words
2026-04-26 08:47:57 +00:00 · 2023-09-04 11:02:32 +02:00
parent 830fde2a60
commit a30092ab42
271 changed files with 6289 additions and 4450 deletions
@@ -1,21 +1,21 @@
 # The `benchmark overhead` command

-Each time an extrinsic or a block is executed, a fixed weight is charged as "execution overhead".
-This is necessary since the weight that is calculated by the pallet benchmarks does not include this overhead.
-The exact overhead to can vary per Substrate chain and needs to be calculated per chain.
-This command calculates the exact values of these overhead weights for any Substrate chain that supports it.
+Each time an extrinsic or a block is executed, a fixed weight is charged as "execution overhead". This is necessary
+since the weight that is calculated by the pallet benchmarks does not include this overhead. The exact overhead to can
+vary per Substrate chain and needs to be calculated per chain. This command calculates the exact values of these
+overhead weights for any Substrate chain that supports it.

 ## How does it work?

-The benchmark consists of two parts; the [`BlockExecutionWeight`] and the [`ExtrinsicBaseWeight`].
-Both are executed sequentially when invoking the command.
+The benchmark consists of two parts; the [`BlockExecutionWeight`] and the [`ExtrinsicBaseWeight`]. Both are executed
+sequentially when invoking the command.

 ## BlockExecutionWeight

-The block execution weight is defined as the weight that it takes to execute an *empty block*.
-It is measured by constructing an empty block and measuring its executing time.
-The result are written to a `block_weights.rs` file which is created from a template.
-The file will contain the concrete weight value and various statistics about the measurements. For example:
+The block execution weight is defined as the weight that it takes to execute an *empty block*. It is measured by
+constructing an empty block and measuring its executing time. The result are written to a `block_weights.rs` file which
+is created from a template. The file will contain the concrete weight value and various statistics about the
+measurements. For example:
 ```rust
 /// Time to execute an empty block.
 /// Calculated by multiplying the *Average* with `1` and adding `0`.
@@ -34,16 +34,17 @@ pub const BlockExecutionWeight: Weight =
    Weight::from_parts(WEIGHT_REF_TIME_PER_NANOS.saturating_mul(3_532_484), 0);
 ```

-In this example it takes 3.5 ms to execute an empty block. That means that it always takes at least 3.5 ms to execute *any* block.
-This constant weight is therefore added to each block to ensure that Substrate budgets enough time to execute it.
+In this example it takes 3.5 ms to execute an empty block. That means that it always takes at least 3.5 ms to execute
+*any* block. This constant weight is therefore added to each block to ensure that Substrate budgets enough time to
+execute it.

 ## ExtrinsicBaseWeight

-The extrinsic base weight is defined as the weight that it takes to execute an *empty* extrinsic.
-An *empty* extrinsic is also called a *NO-OP*. It does nothing and is the equivalent to the empty block form above.
-The benchmark now constructs a block which is filled with only NO-OP extrinsics.
-This block is then executed many times and the weights are measured.
-The result is divided by the number of extrinsics in that block and the results are written to `extrinsic_weights.rs`.
+The extrinsic base weight is defined as the weight that it takes to execute an *empty* extrinsic. An *empty* extrinsic
+is also called a *NO-OP*. It does nothing and is the equivalent to the empty block form above. The benchmark now
+constructs a block which is filled with only NO-OP extrinsics. This block is then executed many times and the weights
+are measured. The result is divided by the number of extrinsics in that block and the results are written to
+`extrinsic_weights.rs`.

 The relevant section in the output file looks like this:
 ```rust
@@ -64,8 +65,9 @@ pub const ExtrinsicBaseWeight: Weight =
    Weight::from_parts(WEIGHT_REF_TIME_PER_NANOS.saturating_mul(67_745), 0);
 ```

-In this example it takes 67.7 µs to execute a NO-OP extrinsic. That means that it always takes at least 67.7 µs to execute *any* extrinsic.
-This constant weight is therefore added to each extrinsic to ensure that Substrate budgets enough time to execute it.
+In this example it takes 67.7 µs to execute a NO-OP extrinsic. That means that it always takes at least 67.7 µs to
+execute *any* extrinsic. This constant weight is therefore added to each extrinsic to ensure that Substrate budgets
+enough time to execute it.

 ## Invocation

@@ -106,15 +108,18 @@ The complete command for Polkadot looks like this:
 cargo run --profile=production -- benchmark overhead --chain=polkadot-dev --wasm-execution=compiled --weight-path=runtime/polkadot/constants/src/weights/
 ```

-This will overwrite the the [block_weights.rs](https://github.com/paritytech/polkadot/blob/c254e5975711a6497af256f6831e9a6c752d28f5/runtime/polkadot/constants/src/weights/block_weights.rs) and [extrinsic_weights.rs](https://github.com/paritytech/polkadot/blob/c254e5975711a6497af256f6831e9a6c752d28f5/runtime/polkadot/constants/src/weights/extrinsic_weights.rs) files in the Polkadot runtime directory.
-You can try the same for *Rococo* and to see that the results slightly differ.
+This will overwrite the the
+[block_weights.rs](https://github.com/paritytech/polkadot/blob/c254e5975711a6497af256f6831e9a6c752d28f5/runtime/polkadot/constants/src/weights/block_weights.rs)
+and
+[extrinsic_weights.rs](https://github.com/paritytech/polkadot/blob/c254e5975711a6497af256f6831e9a6c752d28f5/runtime/polkadot/constants/src/weights/extrinsic_weights.rs)
+files in the Polkadot runtime directory. You can try the same for *Rococo* and to see that the results slightly differ.
 👉 It is paramount to use `--profile=production` and `--wasm-execution=compiled` as the results are otherwise useless.

 ## Output Interpretation

-Lower is better. The less weight the execution overhead needs, the better.
-Since the weights of the overhead is charged per extrinsic and per block, a larger weight results in less extrinsics per block.
-Minimizing this is important to have a large transaction throughput.
+Lower is better. The less weight the execution overhead needs, the better. Since the weights of the overhead is charged
+per extrinsic and per block, a larger weight results in less extrinsics per block. Minimizing this is important to have
+a large transaction throughput.

 ## Arguments

@@ -132,7 +137,10 @@ Minimizing this is important to have a large transaction throughput.
 License: Apache-2.0

 <!-- LINKS -->
-[`ExtrinsicBaseWeight`]: https://github.com/paritytech/substrate/blob/580ebae17fa30082604f1c9720f6f4a1cfe95b50/frame/support/src/weights/extrinsic_weights.rs#L26
-[`BlockExecutionWeight`]: https://github.com/paritytech/substrate/blob/580ebae17fa30082604f1c9720f6f4a1cfe95b50/frame/support/src/weights/block_weights.rs#L26
+[`ExtrinsicBaseWeight`]:
+    https://github.com/paritytech/substrate/blob/580ebae17fa30082604f1c9720f6f4a1cfe95b50/frame/support/src/weights/extrinsic_weights.rs#L26
+[`BlockExecutionWeight`]:
+    https://github.com/paritytech/substrate/blob/580ebae17fa30082604f1c9720f6f4a1cfe95b50/frame/support/src/weights/block_weights.rs#L26

-[System::Remark]: https://github.com/paritytech/substrate/blob/580ebae17fa30082604f1c9720f6f4a1cfe95b50/frame/system/src/lib.rs#L382
+[System::Remark]:
+    https://github.com/paritytech/substrate/blob/580ebae17fa30082604f1c9720f6f4a1cfe95b50/frame/system/src/lib.rs#L382