Merge pull request rubocop#588 from sauloperez/doc-non-goals

dgollahon · web-flow · commit ab0af51748de · 2018-04-18T01:00:59.000-07:00
Add non-goals section documenting should vs expect
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -10,6 +10,7 @@ do so.
 * Check that the issue has not already been reported.
 * Check that the issue has not already been fixed in the latest code
   (a.k.a. `master`).
+* Check if the issue is a non-goal of RuboCop RSpec.
 * Be clear, concise and precise in your description of the problem.
 * Open an issue with a descriptive title and a summary in grammatically correct,
   complete sentences.
diff --git a/README.md b/README.md
@@ -98,6 +98,46 @@ RSpec/FilePath:
     - spec/my_poorly_named_spec_file.rb
 ```
 
+## Non-goals of RuboCop RSpec
+
+### Enforcing `should` vs. `expect` syntax
+
+Enforcing
+
+```ruby
+expect(calculator.compute(line_item)).to eq(5)
+```
+
+over
+
+```ruby
+calculator.compute(line_item).should == 5
+```
+
+is a feature of RSpec itself – you can read about it in the [RSpec Documentation](https://relishapp.com/rspec/rspec-expectations/docs/syntax-configuration#disable-should-syntax)
+
+### Enforcing an explicit RSpec receiver for top-level methods (disabling monkey patching)
+
+Enforcing
+
+```ruby
+Rspec.describe MyClass do
+  ...
+end
+```
+
+over
+
+```ruby
+describe MyClass do
+  ...
+end
+```
+
+can be achieved using RSpec's `disable_monkey_patching!` method, which you can read more about in the [RSpec Documentation](https://relishapp.com/rspec/rspec-core/v/3-7/docs/configuration/zero-monkey-patching-mode#monkey-patched-methods-are-undefined-with-%60disable-monkey-patching!%60). This will also prevent `should` from being defined on every object in your system.
+
+Before disabling `should` you will need all your specs to use the `expect` syntax. You can use [Transpec](http://yujinakayama.me/transpec/), which will do the conversion for you.
+
 
 ## Contributing
 
