1 files changed, 15 insertions, 12 deletions

diff --git a/spec/ruby/CONTRIBUTING.md b/spec/ruby/CONTRIBUTING.md
index adfc2fb0ca..366b484bad 100644
--- a/spec/ruby/CONTRIBUTING.md
+++ b/spec/ruby/CONTRIBUTING.md
@@ -113,9 +113,9 @@ Also `have_constant`, `have_private_instance_method`, `have_singleton_method`, e
 }
 ```
 
-##### should_not raise_error
+##### `should_not raise_error`
 
-**To avoid!** Instead, use an expectation testing what the code in the lambda does.
+**Avoid this!** Instead, use an expectation testing what the code in the lambda does.
 If an exception is raised, it will fail the example anyway.
 
 ```ruby
@@ -138,12 +138,12 @@ Here is a list of the most commonly-used guards:
 #### Version guards
 
 ```ruby
-ruby_version_is ""..."2.6" do
-  # Specs for RUBY_VERSION < 2.6
+ruby_version_is ""..."3.2" do
+  # Specs for RUBY_VERSION < 3.2
 end
 
-ruby_version_is "2.6" do
-  # Specs for RUBY_VERSION >= 2.6
+ruby_version_is "3.2" do
+  # Specs for RUBY_VERSION >= 3.2
 end
 ```
 
@@ -164,7 +164,7 @@ end
 platform_is_not :linux, :darwin do # Not Linux and not Darwin
 end
 
-platform_is wordsize: 64 do
+platform_is pointer_size: 64 do
   # 64-bit platform
 end
 
@@ -179,6 +179,9 @@ In case there is a bug in MRI and the fix will be backported to previous version
 If it is not backported or not likely, use `ruby_version_is` instead.
 First, file a bug at https://bugs.ruby-lang.org/.
 The problem is `ruby_bug` would make non-MRI implementations fail this spec while MRI itself does not pass it, so it should only be used if the bug is/will be fixed and backported.
+Otherwise, non-MRI implementations would have to choose between being incompatible with the latest release of MRI (which has the bug) to pass the spec, or behave the same as the latest release of MRI (which has the bug) and fail the spec, both which make no sense.
+
+IOW, `ruby_bug '#NN', ''...'X.Y' do` is equivalent to `guard_not { RUBY_ENGINE == "ruby" && ruby_version_is ''...'X.Y' } do`. So it skips tests on MRI on specified versions (where a bug is present) and runs tests on alternative implementations only.
 
 ```ruby
 ruby_bug '#13669', ''...'3.2' do
@@ -191,11 +194,11 @@ end
 #### Combining guards
 
 ```ruby
-guard -> { platform_is :windows and ruby_version_is ""..."2.6" } do
-  # Windows and RUBY_VERSION < 2.6
+guard -> { platform_is :windows and ruby_version_is ""..."3.2" } do
+  # Windows and RUBY_VERSION < 3.2
 end
 
-guard_not -> { platform_is :windows and ruby_version_is ""..."2.6" } do
+guard_not -> { platform_is :windows and ruby_version_is ""..."3.2" } do
   # The opposite
 end
 ```
@@ -276,13 +279,13 @@ describe :kernel_sprintf, shared: true do
 end
 
 describe "Kernel#sprintf" do
-  it_behaves_like :kernel_sprintf, -> (format, *args) {
+  it_behaves_like :kernel_sprintf, -> format, *args {
     sprintf(format, *args)
   }
 end
 
 describe "Kernel.sprintf" do
-  it_behaves_like :kernel_sprintf, -> (format, *args) {
+  it_behaves_like :kernel_sprintf, -> format, *args {
     Kernel.sprintf(format, *args)
   }
 end