Move most known issues from README.md -> RELEASE.md

Since all but one of these seems to relate to a specific version or a
set of versions, they're more likely to be useful in the release notes
against the relevant version(s).

I've also tweaked the wording of the remaining known issue.

README.md

@@ -121,13 +121,7 @@ Follow the instructions for the relevant test framework in the [Bundler](#bundle
 
 #### Known Issues
 
-* In Mocha v1.10.0 an undocumented feature of `API#mock`, `API#stub` & `API#stub_everything` was changed. Previously when these methods were passed a single symbol, they returned a mock object that responded to the method identified by the symbol. Now Passing a single symbol is equivalent to passing a single string, i.e. it now defines the 'name' of the mock object.
-* In Mocha v1.2.0 there is a scenario where stubbing a class method originally defined in a module hangs the Ruby interpreter due to [a bug in Ruby v2.3.1](https://bugs.ruby-lang.org/issues/12832). See #272. This was fixed in Mocha v1.2.1.
-* Since v1.1.0 Mocha has used prepended modules internally for stubbing methods. There is [an obscure Ruby bug](https://bugs.ruby-lang.org/issues/12876) in many (but not all) versions of Ruby between v2.0 & v2.3 which under certain circumstances may cause your Ruby interpreter to hang. See the Ruby bug report for more details. The bug has been fixed in Ruby v2.3.3 & v2.4.0.
-* Stubbing an aliased class method, where the original method is defined in a module that's used to `extend` the class doesn't work in Ruby 1.8.x. See stub_method_defined_on_module_and_aliased_test.rb for an example of this behaviour.
-* 0.13.x versions cause a harmless, but annoying, deprecation warning when used with Rails 3.2.0-3.2.12, 3.1.0-3.1.10 & 3.0.0-3.0.19.
-* 0.11.x versions don't work with Rails 3.2.13 (`TypeError: superclass mismatch for class ExpectationError`). See #115.
-* Versions 0.10.2, 0.10.3 & 0.11.0 of the Mocha gem were broken. Please do not use these versions.
+* Prior to v1.15.0 (when support for Ruby v1.8 was dropped), stubbing an aliased class method where the original method is defined in a module that's used to `extend` the class doesn't work in Ruby v1.8. See `test/acceptance/stub_method_defined_on_module_and_aliased_test.rb` for an example of this behaviour.
 
 ### Usage
 

RELEASE.md

@@ -343,6 +343,9 @@ from the Ruby v1.8 standard library are no longer supported (#540,969f4845)
 * Add documentation for Cucumber integration (13ab797b)
 * Add documentation about an undocumented feature of `API#mock`, `API#stub` & `API#stub_everything` being changed (7ed2e4e7, d30c1717)
 
+**WARNING: This release inadvertently changed some undocumented behaviour:**
+* An undocumented feature of `API#mock`, `API#stub` & `API#stub_everything` was changed. Previously when these methods were passed a single symbol, they returned a mock object that responded to the method identified by the symbol. Now Passing a single symbol is equivalent to passing a single string, i.e. it now defines the 'name' of the mock object.
+
 ## 1.10.0.beta.1
 
 * Hide `ClassMethods#method_visibility` & `#method_exists?` methods to avoid clash with Rails (#428)
@@ -486,6 +489,9 @@ from the Ruby v1.8 standard library are no longer supported (#540,969f4845)
 * Fix typo in docs for equals - thanks to @alexcoco (#254)
 * Add known issue for Ruby v1.8 to README - thanks to @chrisroos (2c642096)
 
+**WARNING: This release inadvertently introduced the possibility of causing the Ruby interpreter to hang:**
+* There is a scenario where stubbing a class method originally defined in a module hangs the Ruby interpreter due to [a bug in Ruby v2.3.1](https://bugs.ruby-lang.org/issues/12832). See #272. This was fixed in Mocha v1.2.1.
+
 ## 1.1.0
 
 * Set visibility of any instance stub method.
@@ -494,6 +500,9 @@ from the Ruby v1.8 standard library are no longer supported (#540,969f4845)
 * Use GitHub convention for instructions on contributing to Mocha.
 * Fix typos in docs. Thanks to @10io
 
+**WARNING: This release inadvertently introduced the possibility of causing the Ruby interpreter to hang:**
+* From this release onwards, prepended modules have been used internally for stubbing methods. There is [an obscure Ruby bug](https://bugs.ruby-lang.org/issues/12876) in many (but not all) versions of Ruby between v2.0 & v2.3 which under certain circumstances may cause your Ruby interpreter to hang. See the Ruby bug report for more details. The bug has been fixed in Ruby v2.3.3 & v2.4.0.
+
 ## 1.0.0
 
 ### External changes
@@ -556,6 +565,9 @@ relevant patch version.
 * Adapt Mocha acceptance tests to cope with changes in output from latest (v4.6.2) of MiniTest.
 * Updates to README about Rails compatibility.
 
+**NOTE: This release inadvertently caused deprecation warnings in some contexts:**
+* When used with Rails v3.2.0-v3.2.12, v3.1.0-v3.1.10 & v3.0.0-v3.0.19.
+
 ## 0.13.2
 * Stubbing of methods re-declared with different visibilty. Fixes #109.
 * Add `Mock#responds_like_instance_of`. Fixes #119.
@@ -565,10 +577,16 @@ relevant patch version.
 * Add a Gem Badge to provide a link to Mocha on Rubygems.
 * Make documentation example consistent with other examples.
 
+**NOTE: This release inadvertently caused deprecation warnings in some contexts:**
+* When used with Rails v3.2.0-v3.2.12, v3.1.0-v3.1.10 & v3.0.0-v3.0.19.
+
 ## 0.13.1
 * Fix #97 - `Mocha::ParameterMatchers#has_entry` does not work with an Array as the entry's value. Thanks to @ngokli.
 * Allow deprecation `:debug` mode to be switched on from `MOCHA_OPTIONS` environment variable.
 
+**NOTE: This release inadvertently caused deprecation warnings in some contexts:**
+* When used with Rails v3.2.0-v3.2.12, v3.1.0-v3.1.10 & v3.0.0-v3.0.19.
+
 ## 0.13.0
 * Major overhaul of MiniTest & Test::Unit integration. Mocha now integrates with later versions of the two test libraries using documented hooks rather than monkey-patching. This should mean that Mocha will integrate with new versions of either library without the need to release a new version of Mocha each time, which was clearly bad and unsustainable. Many thanks to @tenderlove, @zenspider & @kou for their help, suggestions & patience.
 * Temporarily deprecated `require 'mocha'`. Use `require 'mocha/setup'` instead. The plan is that eventually `require 'mocha'` will *not* automatically integrate with either of the two test libraries as it does at the moment, and you'll need to explicitly & separately trigger the integration. I think this will provide a lot more flexibility and will hopefully do away with the need for the `require: false` option in the `Gemfile` which has always confused people.
@@ -581,6 +599,9 @@ relevant patch version.
 * Various improvements to automated testing of integration with test libraries.
 * Make deprecation warnings more prominent.
 
+**NOTE: This release inadvertently caused deprecation warnings in some contexts:**
+* When used with Rails v3.2.0-v3.2.12, v3.1.0-v3.1.10 & v3.0.0-v3.0.19.
+
 ## 0.12.7
 * Officially support minitest v4.1.0 (still monkey-patching).
 
@@ -617,15 +638,27 @@ relevant patch version.
 ## 0.11.4
 * Homepage has moved to http://gofreerange.com/mocha/docs.
 
+**WARNING: This release inadvertently included a Rails compatibility issue:**
+* `TypeError: superclass mismatch for class ExpectationError` raised when using Rails v3.2.13. See #115.
+
 ## 0.11.3
 * Fix for #78 i.e. alias Object#method as Object#_method, not Object#__method__ which already exists as another Ruby method.
 
+**WARNING: This release inadvertently included a Rails compatibility issue:**
+* `TypeError: superclass mismatch for class ExpectationError` raised when using Rails v3.2.13. See #115.
+
 ## 0.11.2
 * Rails has a Request class which defines its own #method method. This broke the new mechanism for stubbing a method. This release includes a slightly modified version of fix #77 provided by @sikachu. See https://github.com/rails/rails/pull/5907 for further info.
 
+**WARNING: This release inadvertently included a Rails compatibility issue:**
+* `TypeError: superclass mismatch for class ExpectationError` raised when using Rails v3.2.13. See #115.
+
 ## 0.11.1
 * In Ruby 1.8.7 methods accepting a block parameter were incorrectly restored without the block parameter after being stubbed. Fix for #76.
 
+**WARNING: This release inadvertently included a Rails compatibility issue:**
+* `TypeError: superclass mismatch for class ExpectationError` raised when using Rails v3.2.13. See #115.
+
 ## 0.11.0
 * Store original method when stubbing rather than using alias_method. This fixes #41, #47, #74 and all tests now pass on both Ruby 1.8.7 and 1.9.3.
 * Attempting to stub a method on a frozen object should fail fast. See #68.
@@ -638,6 +671,11 @@ relevant patch version.
 * Improve documentation for ObjectMethods.
 * Provide a way to run multiple tests within a single acceptance test method.
 
+**WARNING: This release inadvertently included a significant bug - please do not use it!**
+
+**WARNING: This release inadvertently introduced a Rails compatibility issue:**
+* `TypeError: superclass mismatch for class ExpectationError` raised when using Rails v3.2.13. See #115.
+
 ## 0.10.5
 * Fix for issue #66 (hopefully without regressing on issue #63) - Mocha::Mock has Mocha::Mockery as a dependency. Stop trying to pretend otherwise. Thanks to @kennyj for reporting.
 * Fix a bunch of warnings in Ruby 1.9. There are still the 6 test failures mentioned in issue #41 which I suspect are due to the introspection gem not being Ruby 1.9-compatible.
@@ -656,9 +694,13 @@ Hash with wrong number of entries.
 ## 0.10.3
 * Fix for issue #57. Gem::Requirement#=~ was only added in rubygems v1.8.0, but Object#=~ means the result of various monkey-patching checks is always false/nil for earlier versions of rubygems. However, the method it aliases #satisfied_by? has existed since Gem::Dependency was extracted from Gem::Version in rubygems v0.9.4.4, so it's much safer to use that. Thanks to fguillen for reporting and helping with diagnosis.
 
+**WARNING: This release inadvertently included a significant bug - please do not use it!**
+
 ## 0.10.2
 * Merge pull request #53. Unstubbing a method should not remove expectations for other stubbed methods. Fixes #52. Thanks to saikat.
 
+**WARNING: This release inadvertently included a significant bug - please do not use it!**
+
 ## 0.10.1
 * Merge pull request #51. Use Gem::Requirement & Gem::Version for version comparison. Fixes issue #50. Thanks to meineerde.
 * Fixed typo in rdoc for Mocha::ObjectMethods.