MONGOID-5217 Add _previously_was methods (#5195)

Author: comandeo-mongo

source/release-notes/mongoid-8.0.txt

@@ -169,7 +169,7 @@ Mongoid 8.0 behavior:
 
   Band.any_of({name: 'Rolling Stone'}, {founded: 1990}).
     any_of({members: 2}, {last_tour: 1995})
-  # => 
+  # =>
   # #<Mongoid::Criteria
   #   selector: {"$or"=>[{"name"=>"Rolling Stone"}, {"founded"=>1990}],
   #     "$and"=>[{"$or"=>[{"members"=>2}, {"last_tour"=>1995}]}]}
@@ -178,7 +178,7 @@ Mongoid 8.0 behavior:
   #   embedded: false>
 
   Band.any_of({name: 'Rolling Stone'}, {founded: 1990}).any_of({members: 2})
-  # => 
+  # =>
   # #<Mongoid::Criteria
   #   selector: {"$or"=>[{"name"=>"Rolling Stone"}, {"founded"=>1990}], "members"=>2}
   #   options:  {}
@@ -191,7 +191,7 @@ Mongoid 7 behavior:
 
   Band.any_of({name: 'Rolling Stone'}, {founded: 1990}).
     any_of({members: 2}, {last_tour: 1995})
-  # => 
+  # =>
   # #<Mongoid::Criteria
   #   selector: {"$or"=>[{"name"=>"Rolling Stone"}, {"founded"=>1990},
   #     {"members"=>2}, {"last_tour"=>1995}]}
@@ -200,7 +200,7 @@ Mongoid 7 behavior:
   #   embedded: false>
 
   Band.any_of({name: 'Rolling Stone'}, {founded: 1990}).any_of({members: 2})
-  # => 
+  # =>
   # #<Mongoid::Criteria
   #   selector: {"$or"=>[{"name"=>"Rolling Stone"}, {"founded"=>1990}], "members"=>2}
   #   options:  {}
@@ -248,3 +248,31 @@ Mongoid 7 output:
 
 Notice that in 7 ``attribute_was(:age)`` returns the old attribute value,
 while in 8.0 ``attribute_was(:age)`` returns the new value.
+
+``*_previously_was``, ``previously_new_record?``, and ``previously_persisted?`` helpers
+---------------------------------------------------------------------------------------
+
+Mongoid 8.0 introduces ActiveModel-compatible ``*_previously_was`` helpers,
+as well as ActiveRecord-compatible ``previously_new_record?`` and
+``previously_persisted?`` helpers:
+
+.. code-block:: ruby
+
+  class User
+    include Mongoid::Document
+
+    field :name, type: String
+    field :age, type: Integer
+  end
+
+  user = User.create!(name: 'Sam', age: 18)
+  user.previously_new_record?     # => true
+
+  user.name = "Nick"
+  user.save!
+  user.name_previously_was        # => "Sam"
+  user.age_previously_was         # => 18
+  user.previously_new_record?     # => false
+
+  user.destroy
+  user.previously_persisted?   # => true