MONGOID-4979 Add :touch option to model save method (#5397)

* MONGOID-4979 test set_created_at

* MONGOID-4979 undo test

* MONGOID-4979 add touch: false option

* MONGOID-4979 use the timeless method instead

* MONGOID-4979 add optimization and timeless tests

* MONGOID-4979 fix docs

* MONGOID-4979 add release note

* MONGOID-4979 add crud docs

Author: neilshweky

source/reference/crud.txt

@@ -145,6 +145,11 @@ operations with examples.
        the save.*
 
        *Pass* ``validate: false`` *option to bypass validations.*
+
+       *Pass* ``touch: false`` *option to ignore the updates to the updated_at
+       field. If the document being save has not been previously persisted,
+       this option is ignored and the created_at and updated_at fields will be
+       updated with the current time.*
      -
         .. code-block:: ruby
 
@@ -154,6 +159,7 @@ operations with examples.
           )
           person.save
           person.save(validate: false)
+          person.save(touch: false)
 
           person.first_name = "Christian Johan"
           person.save

source/release-notes/mongoid-8.1.txt

@@ -42,3 +42,18 @@ with a bang (!) raise an error:
 
   Band.none.first!
   # => raise Mongoid::Errors::DocumentNotFound
+
+
+Added ``:touch`` option to ``#save``
+------------------------------------
+
+Support for the ``:touch`` option has been added to the ``#save`` and ``#save!``
+methods. When this option is false, the ``updated_at`` field on the saved
+document and all of it's embedded documents will not be updated with the
+current time. When this option is true or unset, the ``updated_at`` field will
+be updated with the current time.
+
+If the document being saved is a new document (i.e. it has not yet been
+persisted to the database), then the ``:touch`` option will be ignored, and the
+``updated_at`` (and ``created_at``) fields will be updated with the current
+time.