MONGOID-5474/MONGOID-5478 add docs and release notes (#5457)

* MONGOID-5474 add docs and release notes

* MONGOID-5474 use read-only

* MONGOID-5474 add configuration docs

* MOGOID-5474 switch order of flag docs

* add MONGOID-5477 use case

Author: neilshweky

source/reference/configuration.txt

@@ -383,6 +383,17 @@ for details on driver options.
       # (default: false)
       #legacy_pluck_distinct: true
 
+      # When this flag is false, a document will become read-only only once the
+      # #readonly! method is called, and an error will be raised on attempting
+      # to save or update such documents, instead of just on delete. When this
+      # flag is true, a document is only read-only if it has been projected
+      # using #only or #without, and read-only documents will not be
+      # deletable/destroyable, but will be savable/updatable.
+      # When this feature flag is turned on, the read-only state will be reset on
+      # reload, but when it is turned off, it won't be.
+      # (default: true)
+      legacy_readonly: false
+
       # Maintain legacy behavior of === on Mongoid document classes, which
       # returns true in a number of cases where Ruby's === implementation would
       # return false. Note that the behavior of === on Mongoid document

source/reference/crud.txt

@@ -974,3 +974,69 @@ back to the model as follows:
 
   band.tours
   # => #<Set: {"London"}>
+
+
+.. _readonly-documents:
+
+Readonly Documents
+==================
+
+Documents can be marked read-only in two ways, depending on the value of the
+``Mongoid.legacy_readonly`` feature flag:
+
+If this flag is turned off, a document is marked read-only when the ``#readonly!``
+method is called on that documnet. A read-only document, with this flag turned off,
+will raise a ReadonlyDocument error on attempting to perform any persistence
+operation, including (but not limited to) saving, updating, deleting and
+destroying. Note that reloading does not reset the read-only state.
+
+.. code:: ruby
+
+  band = Band.first
+  band.readonly? # => false
+  band.readonly!
+  band.readonly? # => true
+  band.name = "The Rolling Stones"
+  band.save # => raises ReadonlyDocument error
+  band.reload.readonly? # => true
+
+If this flag is turned on, a document is marked read-only when that document
+has been projected (i.e. using ``#only`` or ``#without``). A read-only document,
+with this flag turned on, will not be deletable or destroyable (a
+``ReadonlyDocument`` error will be raised), but will be saveable and updatable.
+The read-only status is reset on reloading the document.
+
+.. code:: ruby
+
+  class Band
+    include Mongoid::Document
+    field :name, type: String
+    field :genre, type: String
+  end
+
+  band = Band.only(:name).first
+  band.readonly? # => true
+  band.destroy # => raises ReadonlyDocument error
+  band.reload.readonly? # => false
+
+
+Overriding ``readonly?``
+------------------------
+
+Another way to make a document read-only is by overriding the readonly? method:
+
+.. code:: ruby
+
+  class Band
+    include Mongoid::Document
+    field :name, type: String
+    field :genre, type: String
+
+    def readonly?
+      true
+    end
+  end
+
+  band = Band.first
+  band.readonly? # => true
+  band.destroy # => raises ReadonlyDocument error

source/reference/fields.txt

@@ -1648,7 +1648,7 @@ Assignments to read-only attributes using their setters will be ignored:
   # => "The Rolling Stones"
 
 Calls to atomic persistence operators, like ``bit`` and ``inc``, will persist
-changes to readonly fields.
+changes to read-only fields.
 
 Timestamp Fields
 ================

source/release-notes/mongoid-8.1.txt

@@ -17,6 +17,7 @@ The complete list of releases is available `on GitHub
 please consult GitHub releases for detailed release notes and JIRA for
 the complete list of issues fixed in each release, including bug fixes.
 
+
 Added ``attribute_before_last_save``, ``saved_change_to_attribute``, ``saved_change_to_attribute?``, and ``will_save_change_to_attribute?``  methods
 ----------------------------------------------------------------------------------------------------------------------------------------------------
 
@@ -239,3 +240,45 @@ documents should be stored in using the ``store_in`` macro:
 Previously, an error was raised if this was done. See the section on
 :ref:`Inheritance Persistence Context <inheritance-persistence-context>`
 for more details.
+
+
+Added ``readonly!`` method and ``legacy_readonly`` feature flag
+---------------------------------------------------------------
+
+Mongoid 8.1 changes the meaning of read-only documents. In Mongoid 8.1 with 
+this feature flag turned off, a document becomes read-only when calling the 
+``readonly!`` method:
+
+.. code:: ruby
+
+  band = Band.first
+  band.readonly? # => false
+  band.readonly!
+  band.readonly? # => true
+  band.name = "The Rolling Stones"
+  band.save # => raises ReadonlyDocument error
+
+With this feature flag turned off, a ``ReadonlyDocument`` error will be
+raised when destroying or deleting, as well as when saving or updating.
+
+Prior to Mongoid 8.1 and in 8.1 with the ``legacy_readonly`` feature flag 
+turned on, documents become read-only when they are projected (i.e. using 
+``#only`` or ``#without``).
+
+.. code:: ruby
+
+  class Band
+    include Mongoid::Document
+    field :name, type: String
+    field :genre, type: String
+  end
+
+  band = Band.only(:name).first
+  band.readonly? # => true
+  band.destroy # => raises ReadonlyDocument error
+
+Note that with this feature flag on, a ``ReadonlyDocument`` error will only be
+raised when destroying or deleting, and not on saving or updating. See the 
+section on :ref:`Read-only Documents <readonly-documents>` for more details.
+
+