Expand and clarify documentation about version guards for specs

1 files changed, 35 insertions, 5 deletions

diff --git a/spec/README.md b/spec/README.md
index 59c2c605c5..1b2e4d5f53 100644
--- a/spec/README.md
+++ b/spec/README.md
@@ -30,13 +30,43 @@ In other words: If adding a spec might reveal a bug in
 another implementation, then it is worth adding it.
 Currently, the only module which is MRI-specific is `RubyVM`.
 
+## Changing behavior and versions guards
+
 Version guards (`ruby_version_is`) must be added for new features or features
-which change behavior or are removed. See `spec/ruby/CONTRIBUTING.md` for details.
+which change behavior or are removed. This is necessary for other Ruby implementations
+to still be able to run the specs and contribute new specs.
+
+For example, change:
+```ruby
+describe "Some spec" do
+  it "some example" do
+    # Old behavior for Ruby < 2.7
+  end
+end
+```
+to:
+```ruby
+describe "Some spec" do
+  ruby_version_is ""..."2.7" do
+    it "some example" do
+      # Old behavior for Ruby < 2.7
+    end
+  end
+
+  ruby_version_is "2.7" do
+    it "some example" do
+      # New behavior for Ruby >= 2.7
+    end
+  end
+end
+```
+
+See `spec/ruby/CONTRIBUTING.md` for more documentation about guards.
 
 To verify specs are compatible with older Ruby versions:
 ```
 cd spec/ruby
-$RUBY_MANAGER use 2.3.7
+$RUBY_MANAGER use 2.4.6
 ../mspec/bin/mspec -j
 ```
 
@@ -73,8 +103,8 @@ spec/mspec/bin/mspec spec/ruby/language/for_spec.rb
 
 ## ruby/spec and test/
 
-The main difference between a "spec" under spec/ruby and
-a test under test/ is that specs are documenting what they test.
+The main difference between a "spec" under `spec/ruby/` and
+a test under `test/` is that specs are documenting what they test.
 This is extremely valuable when reading these tests, as it
 helps to quickly understand what specific behavior is tested,
 and how a method should behave. Basic English is fine for spec descriptions.
@@ -97,4 +127,4 @@ describe "The for expression" do
 end
 ```
 
-For more details, see spec/ruby/CONTRIBUTING.md.
+For more details, see `spec/ruby/CONTRIBUTING.md`.