Merge pull request #26792 from rails/benchmark-template

Introduce a benchmark template

2 files changed, 67 insertions, 27 deletions

diff --git a/guides/bug_report_templates/benchmark.rb b/guides/bug_report_templates/benchmark.rb
new file mode 100644
index 0000000000..ae51d7027f
--- /dev/null
+++ b/guides/bug_report_templates/benchmark.rb
@@ -0,0 +1,49 @@
+begin
+  require "bundler/inline"
+rescue LoadError => e
+  $stderr.puts "Bundler version 1.10 or later is required. Please update your Bundler"
+  raise e
+end
+
+gemfile(true) do
+  source "https://rubygems.org"
+  gem "rails", github: "rails/rails"
+  gem "benchmark-ips"
+end
+
+require "active_support"
+require "active_support/core_ext/object/blank"
+
+# Your patch goes here.
+class String
+  def fast_blank?
+    true
+  end
+end
+
+# Enumerate some representative scenarios here.
+#
+# It is very easy to make an optimization that improves performance for a
+# specific scenario you care about but regresses on other common cases.
+# Therefore, you should test your change against a list of representative
+# scenarios. Ideally, they should be based on real-world scenarios extracted
+# from production applications.
+SCENARIOS = {
+  "Empty"            => "",
+  "Single Space"     => " ",
+  "Two Spaces"       => "  ",
+  "Mixed Whitspaces" => " \t\r\n",
+  "Very Long String" => " " * 100
+}
+
+SCENARIOS.each_pair do |name, value|
+  puts
+  puts " #{name} ".center(80, "=")
+  puts
+
+  Benchmark.ips do |x|
+    x.report('blank?')      { value.blank? }
+    x.report('fast_blank?') { value.fast_blank? }
+    x.compare!
+  end
+end
diff --git a/guides/source/contributing_to_ruby_on_rails.md b/guides/source/contributing_to_ruby_on_rails.md
index 4f938f5deb..5791e7a12a 100644
--- a/guides/source/contributing_to_ruby_on_rails.md
+++ b/guides/source/contributing_to_ruby_on_rails.md
@@ -270,33 +270,24 @@ The above are guidelines - please use your best judgment in using them.
 
 ### Benchmark Your Code
 
-If your change has an impact on the performance of Rails, please use the
-[benchmark-ips](https://github.com/evanphx/benchmark-ips) gem to provide
-benchmark results for comparison.
-
-Here's an example of using benchmark-ips:
-
-```ruby
-require 'benchmark/ips'
-
-Benchmark.ips do |x|
-  x.report('addition') { 1 + 2 }
-  x.report('addition with send') { 1.send(:+, 2) }
-end
-```
-
-This will generate a report with the following information:
-
-```
-Calculating -------------------------------------
-            addition   132.013k i/100ms
-  addition with send   125.413k i/100ms
--------------------------------------------------
-            addition      9.677M (± 1.7%) i/s -     48.449M
-  addition with send      6.794M (± 1.1%) i/s -     33.987M
-```
-
-Please see the benchmark/ips [README](https://github.com/evanphx/benchmark-ips/blob/master/README.md) for more information.
+For changes that might have an impact on performance, please benchmark your
+code and measure the impact. Please share the benchmark script you used as well
+as the results. You should consider including these information in your commit
+message, which allows future contributors to easily verify your findings and
+determine if they are still relevant. (For example, future optimizations in the
+Ruby VM might render certain optimizations unnecessary.)
+
+It is very easy to make an optimization that improves performance for a
+specific scenario you care about but regresses on other common cases.
+Therefore, you should test your change against a list of representative
+scenarios. Ideally, they should be based on real-world scenarios extracted
+from production applications.
+
+You can use the [benchmark template](https://github.com/rails/rails/blob/master/guides/bug_report_templates/benchmark.rb)
+as a starting point. It includes the boilerplate code to setup a benchmark
+using the [benchmark-ips](https://github.com/evanphx/benchmark-ips) gem. The
+template is designed for testing relatively self-contained changes that can be
+inlined into the script.
 
 ### Running Tests