From 0f0aabf9da9865a9c623a7be95413305b29cfab9 Mon Sep 17 00:00:00 2001
From: Gregory Paidis
 <115458417+gregory-paidis-sonarsource@users.noreply.github.com>
Date: Fri, 15 Dec 2023 17:39:01 +0100
Subject: [PATCH] Add documentation about benchmark results (#3508)

---
 docs/benchmarks.adoc | 45 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 docs/benchmarks.adoc

diff --git a/docs/benchmarks.adoc b/docs/benchmarks.adoc
new file mode 100644
index 00000000000..20de97b8d84
--- /dev/null
+++ b/docs/benchmarks.adoc
@@ -0,0 +1,45 @@
+= Benchmarks
+
+When writing a rule that has to do with performance, you might need to showcase some benchmarks as proof of potential improvements. This should be included in a separate section called `Benchmarks`, under `Resources`.
+
+The format of the benchmarks section is as follows:
+
+* Benchmark table
+* Benchmarking code
+* Hardware configuration
+
+== Benchmark table
+
+- Do not use abbreviations for statistical terms, not everyone is familiar with them.
+- Add links to Wikipedia to explain statistical terms at the header of each column.
+
+Ideally, the columns should look like the following example:
+
+|===
+| <What is being measured> | https://en.wikipedia.org/wiki/Arithmetic_mean[Mean] | https://en.wikipedia.org/wiki/Standard_deviation[Standard Deviation] | https://en.wikipedia.org/wiki/Memory_management[Allocated]
+| <This> | 5.042 ms | 0.1049 ms | 125 KB
+| <That> | 2.691 ms | 0.0334 ms | 85.94 KB
+|===
+
+== Benchmarking code
+
+The code that was used to generate the benchmarks should be included to provide transparency and allow others to reproduce and verify the results. Preferably, the code snippet should include the sample size, the number of iterations, and the framework/library used to run the benchmarks.
+
+If the code is not showcasing how the results were generated, consider prefixing it with an explanation that links to the framework/library used, for example:
+
+----
+The results were generated by running the following snippet with https://github.com/dotnet/BenchmarkDotNet[BenchmarkDotNet].
+----
+
+== Hardware configuration
+
+The hardware configuration used to run the benchmarks should be included, for example:
+
+[source]
+----
+BenchmarkDotNet=v0.13.5, OS=Windows 10 (10.0.19045.2846/22H2/2022Update)
+11th Gen Intel Core i7-11850H 2.50GHz, 1 CPU, 16 logical and 8 physical cores
+  [Host]               : .NET Framework 4.8 (4.8.4614.0), X64 RyuJIT VectorSize=256
+  .NET 7.0             : .NET 7.0.5 (7.0.523.17405), X64 RyuJIT AVX2
+  .NET Framework 4.6.2 : .NET Framework 4.8 (4.8.4614.0), X64 RyuJIT VectorSize=256
+----
\ No newline at end of file