mongoid 2.4.10 → 3.0.0

data/CHANGELOG.md

@@ -3,10 +3,945 @@
 For instructions on upgrading to newer versions, visit
 [mongoid.org](http://mongoid.org/docs/upgrading.html).
 
-## 2.4.11 (branch: 2.4.0-stable)
+## 3.0.0
+
+### New Features
+
+* \#2151 When asking for metadata before persistence, Mongoid will now
+  raise a `Mongoid::Errors::NoMetadata` error if the metadata is not
+  present.
+
+* \#2147 `Model#becomes` now copies over the embedded documents.
+
+* A new callback has been introduced: `upsert`, which runs when calling
+  `document.upsert` since Mongoid does not know if the document is to be
+  treated as new or persisted. With this come the model callbacks:
+
+        before_upsert
+        after_upsert
+        around_upsert
+
+* \#2080/\#2087 The database or session that Mongoid persists to can now be
+  overridden on a global level for cases where `Model#with` is not a viable
+  option.
+
+        Mongoid.override_database(:secondary)
+        Mongoid.override_session(:secondary)
+
+        Band.create(name: "Placebo") #=> Persists to secondary.
+        band.albums.create #=> Persists to secondary.
+
+    Note that this option is global and overrides for all models on the current
+    thread. It is the developer's responsibility to remember to set this back
+    to nil if you no longer want the override to happen.
+
+        Mongoid.override_database(nil)
+        Mongoid.override_session(nil)
+
+* \#1989 Criteria `count`, `size` and `length` now behave as Active Record
+  with regards to database access.
+
+    `Criteria#count` will always hit the database to get the count.
+
+    `Criteria#length` and `Criteria#size` will hit the database once if the
+    criteria has not been loaded, and subsequent calls will return the
+    cached value.
+
+    If the criteria has been iterated over or loaded, `length` and `size`
+    will never hit the db.
+
+* \#1976 Eager loading no longer produces queries when the base query returns
+  zero results.
+
+* `Model.find_by` now accepts a block and will yield to the found document if
+  it is not nil.
+
+        Band.find_by(name: "Depeche Mode") do |band|
+          band.likes = 100
+        end
+
+* \#1958/\#1798 Documents and `belongs_to` relations now support touch.
+
+        class Band
+          include Mongoid::Document
+          include Mongoid::Timestamps::Updated
+          belongs_to :label, touch: true
+        end
+
+    Update the document's updated_at timestamp to the current time. This
+    will also update any touchable relation's timestamp as well.
+
+        Band.first.touch
+
+    Update a specific time field along with the udpated_at.
+
+        Band.first.touch(:founded)
+
+    This fires no validations or callbacks.
+
+* Mongoid now supports MongoDB's $findAndModify command.
+
+        Band.find_and_modify("$inc" => { likes: 1 })
+
+        Band.desc(:name).only(:name).find_and_modify(
+          { "$inc" => { likes: 1 }}, new: true
+        )
+
+* \#1906 Mongoid will retrieve documents from the identity map when
+  providing multiple ids to find. (Hans Hasselberg)
+
+* \#1903 Mongoid raises an error if provided a javascript expression
+  to a where clause on an embedded collection. (Sebastien Azimi)
+
+* Aggregations now adhere to both a Mongoid API and their enumerable
+  counterparts where applicable.
+
+        Band.min(:likes)
+        Band.min do |a, b|
+          a.likes <=> b.likes
+        end
+
+        Band.max(:likes)
+        Band.max do |a, b|
+          a.likes <=> b.likes
+        end
+
+    Note that when providing a field name and no block, a single numeric
+    value will be returned, but when providing a block, a document will
+    be returned which has the min/max value. This is since Ruby's
+    Enumerable API dictates when providing a block, the matching element
+    is returned.
+
+    When providing a block, all documents will be loaded into memory.
+    When providing a symbol, the execution is handled via map/reduce on
+    the server.
+
+* A kitchen sink aggregation method is now provided, to get everything in
+  in a single call for a field.
+
+        Band.aggregates(:likes)
+        # =>
+        #   {
+        #     "count" => 2.0,
+        #     "max" => 1000.0,
+        #     "min" => 500.0,
+        #     "sum" => 1500.0,
+        #     "avg" => 750.0
+        #   }
+
+* A DSL off the criteria API is now provided for map/reduce operations
+  as a convenience.
+
+        Band.where(name: "Tool").map_reduce(map, reduce).out(inline: 1)
+        Band.map_reduce(map, reduce).out(replace: "coll-name")
+        Band.map_reduce(map, reduce).out(inline: 1).finalize(finalize)
+
+* Mongoid now uses Origin for its Criteria API. See the Origin repo
+  and API docs for the documentation.
+
+* \#1861 Mongoid now raises an `AmbiguousRelationship` error when it
+  cannot determine the inverse of a relation and there are multiple
+  potential candidates. (Hans Hasselberg)
+
+* You can now perform an explain directly from criteria.
+
+        Band.where(name: "Depeche Mode").explain
+
+* \#1856 Push on one to many relations can now be chained.
+
+        band.albums.push(undertow).push(aenima)
+
+* \#1842 MultiParameterAttributes now supported aliased fields.
+  (Anton Orel)
+
+* \#1833 If an embedded document is attempted to be saved with no
+  parent defined, Mongoid now will raise a `Mongoid::Errors::NoParent`
+  exception.
+
+* Added an ORM-agnostic way to get the field names
+
+        class Band
+          include Mongoid::Document
+          field :name, type: String
+        end
+
+        Band.attribute_names
+
+* \#1831 `find_or_create_by` on relations now takes mass assignment
+  and type options. (Tatsuya Ono)
+
+        class Band
+          include Mongoid::Document
+          embeds_many :albums
+        end
+
+        band.albums.find_or_create_by({ name: "101" }, LP)
+
+* \#1818 Add capability to choose the key where your `embeds_many` relation
+  is stores. (Cyril Mougel)
+
+        class User
+          include Mongoid::Document
+          field :name, type: String
+          embeds_many :prefs, class_name: "Preference", store_as: 'my_preferences'
+        end
+
+        user.prefs.build(value: "ok")
+        user.save
+        # document saves in MongoDB as:
+        # { "name" => "foo", "my_preferences" => [{ "value" => "ok" }]}
+
+* \#1806 `Model.find_or_create_by` and `Model.find_or_initialize_by` can now
+  take documents as paramters for belongs_to relations.
+
+        person = Person.first
+        Game.find_or_create_by(person: person)
+
+* \#1774 Relations now have a :restrict option for dependent relations
+  which will raise an error when attempting to delete a parent that
+  still has children on it. (Hans Hasselberg)
+
+        class Band
+          include Mongoid::Document
+          has_many :albums, dependent: :restrict
+        end
+
+        band = Band.first
+        band.albums << Albums.first
+        band.delete # Raises DeleteRestriction error.
+
+* \#1764 Add method to check if field differs from the default value.
+
+        class Band
+          include Mongoid::Document
+          field :name, type: String, default: "New"
+        end
+
+        band = Band.first
+        band.name_changed_from_default?
+
+* \#1759 Invalid fields error messages have been updated to show the
+  source and location of the original method. The new message is:
+
+        Problem:
+          Defining a field named 'crazy_method' is not allowed.
+        Summary:
+          Defining this field would override the method 'crazy_method',
+          which would cause issues with expectations around the original
+          method and cause extremely hard to debug issues.
+          The original method was defined in:
+            Object: MyModule
+            File: /path/to/my/module.rb
+            Line: 8
+        Resolution:
+          Use Mongoid.destructive_fields to see what names are
+          not allowed, and don't use these names. These include names
+          that also conflict with core Ruby methods on Object, Module,
+          Enumerable, or included gems that inject methods into these
+          or Mongoid internals.
+
+* \#1753/#1649 A setter and getter for has_many relations to set it's
+  children is now provided. (Piotr Jakubowski)
+
+        class Album
+          include Mongoid::Document
+          has_many :engineers
+        end
+
+        class Engineer
+          include Mongoid::Document
+          belongs_to :album
+        end
+
+        album = Album.first
+        engineer = Engineer.first
+        album.engineer_ids = [ engineer.id ]
+        album.engineer_ids # Returns the ids of the engineers.
+
+* \#1741 Mongoid now provides a rake task to force remove indexes for
+  environments where Mongoid manages the index definitions and the
+  removal should be automated. (Hans Hasselberg)
+
+        rake db:force_remove_indexes
+        rake db:mongoid:force_remove_indexes
+
+* \#1726 `Mongoid.load!` now accepts an optional second argument for the
+  environment to load. This takes precedence over any environment variable
+  that is set if provided.
+
+        Mongoid.load!("/path/to/mongoid.yml", :development)
+
+* \#1724 Mongoid now supports regex fields.
+
+        class Rule
+          include Mongoid::Document
+          field :pattern, type: Regexp, default: /[^abc]/
+        end
+
+* \#1714/\#1706 Added better logging on index creation. (Hans Hasselberg)
+
+    When an index is present on a root document model:
+
+        Creating indexes on: Model for: name, dob.
+
+    When an index is defined on an embedded model:
+
+        Index ignored on: Address, please define in the root model.
+
+    When no index is defined, nothing is logged, and if a bad index is
+    defined an error is raised.
+
+* \#1710 For cases when you don't want Mongoid to auto-protect the id
+  and type attributes, you can set a configuration option to turn this
+  off.
+
+        Mongoid.protect_sensitive_fields = false
+
+* \#1685 Belongs to relations now have build_ and create_ methods.
+
+        class Comment
+          include Mongoid::Document
+          belongs_to :user
+        end
+
+        comment = Comment.new
+        comment.build_user # Build a new user object
+        comment.create_user # Create a new user object
+
+* \#1684 Raise a `Mongoid::Errors::InverseNotFound` when attempting to
+  set a child on a relation without the proper inverse_of definitions
+  due to Mongoid not being able to determine it.
+
+        class Lush
+          include Mongoid::Document
+          embeds_one :whiskey, class_name: "Drink"
+        end
+
+        class Drink
+          include Mongoid::Document
+          embedded_in :alcoholic, class_name: "Lush"
+        end
+
+        lush = Lush.new
+        lush.whiskey = Drink.new # raises an InverseNotFound error.
+
+* \#1680 Polymorphic relations now use `*_type` keys in lookup queries.
+
+        class User
+          include Mongoid::Document
+          has_many :comments, as: :commentable
+        end
+
+        class Comment
+          include Mongoid::Document
+          belongs_to :commentable, polymorphic: true
+        end
+
+        user = User.find(id)
+        user.comments # Uses user.id and type "User" in the query.
+
+* \#1677 Support for parent separable polymorphic relations to the same
+  parent class is now available. This only works if set from the parent
+  side in order to know which relation the children belong to.
+  (Douwe Maan)
+
+        class Face
+          include Mongoid::Document
+          has_one :left_eye, class_name: "Eye", as: :visible
+          has_one :right_eye, class_name: "Eye", as: :visible
+        end
+
+        class Eye
+          include Mongoid::Document
+          belongs_to :visible, polymorphic: true
+        end
+
+        face = Face.new
+        right_eye = Eye.new
+        left_eye = Eye.new
+        face.right_eye = right_eye
+        face.left_eye = left_eye
+        right_eye.visible = face # Will raise an error.
+
+* \#1650 Objects that respond to `to_criteria` can now be merged into
+  existing criteria objects.
+
+        class Filter
+          def to_criteria
+            # return a Criteria object.
+          end
+        end
+
+        criteria = Person.where(title: "Sir")
+        criteria.merge(filter)
+
+* \#1635 All exceptions now provide more comprehensive errors, including
+  the problem that occured, a detail summary of why it happened, and
+  potential resolutions. Example:
+
+        (Mongoid::Errors::DocumentNotFound)
+        Problem:
+          Document not found for class Town with
+          id(s) [BSON::ObjectId('4f35781b8ad54812e1000001')].
+        Summary:
+          When calling Town.find with an id or array of ids,
+          each parameter must match a document in the database
+          or this error will be raised.
+        Resolution:
+          Search for an id that is in the database or set the
+          Mongoid.raise_not_found_error configuration option to
+          false, which will cause a nil to be returned instead
+          of raising this error.
+
+* \#1616 `Model.find_by` added which takes a hash of arugments to search
+  for in the database. If no single document is returned a DocumentNotFound
+  error is raised. (Piotr Jakubowski)
+
+        Band.find_by(name: "Depeche Mode")
+
+* \#1606 Mongoid now enables autosave, like Active Record, when adding
+  an accepts_nested_attributes_for to a relation.
+
+        class Band
+          include Mongoid::Document
+          has_many :albums
+          accepts_nested_attributes_for :albums # This enables the autosave.
+        end
+
+* \#1477 Mongoid now automatically protects the id and type attributes
+  from mass assignment. You can override this (not recommended) by redefining
+  them as accessible.
+
+        class Band
+          include Mongoid::Document
+          attr_accessible :id, :_id, :_type
+        end
+
+* \#1459 The identity map can be disabled now for specific code execution
+  by passing options to the unit of work.
+
+        Mongoid.unit_of_work(disable: :all) do
+          # Disables the identity map on all threads for the block.
+        end
+
+        Mongoid.unit_of_work(disable: :current) do
+          # Disables the identity map on the current thread for the block.
+        end
+
+        Mongoid.unit_of_work do
+          # Business as usual.
+        end
+
+* \#1355 Associations now can have safety options provided to them on single
+  document persistence operations.
+
+        band.albums.with(safe: true).push(album)
+        band.albums.with(safe: true).create(name: "Smiths")
+
+        album.with(safe: true).create_producer(name: "Flood")
+
+* \#1348 Eager loading is now supported on many-to-many relations.
+
+* \#1292 Remove attribute now unsets the attribute when the document is
+  saved instead of setting to nil.
+
+        band = Band.find(id)
+        band.remove_attribute(:label) # Uses $unset when the document is saved.
+
+* \#1291 Mongoid database sessions are now connected to lazily, and are
+  completely thread safe. If a new thread is created, then a new database
+  session will be created for it.
+
+* \#1291 Mongoid now supports any number of database connections as defined in
+  the mongoid.yml. For example you could have a local single server db, a
+  multi availablity zone replica set, and a shard cluster all in the same
+  application environment. Mongoid can connect to any session at any point in
+  time.
+
+* \#1291 Mongoid now allows you to persist to whatever database or collection
+  you like at runtime, on a per-query or persistence operation basis by using
+  `with`.
+
+        Band.with(collection: "artists").create(name: "Depeche Mode")
+        band.with(database: "secondary).save!
+        Band.with(collection: "artists").where(name: "Depeche Mode")
+
+* \#1291 You can now configure on a per-model basis where it's documents are
+  stored with the new and improved `store_in` macro.
+
+        class Band
+          include Mongoid::Document
+          store_in collection: "artists", database: "secondary", session: "replica"
+        end
+
+    This can be overridden, of course, at runtime via the `with` method.
+
+* \#1212 Embedded documents can now be popped off a relation with persistence.
+
+        band.albums.pop # Pop 1 document and persist the removal.
+        band.albums.pop(3) # Pop 3 documents and persist the removal.
+
+* \#1188 Relations now have existence predicates for simplified checking if the
+  relation is blank or not. (Andy Morris)
+
+        class Band
+          include Mongoid::Document
+          embeds_many :albums
+          embeds_one :label
+        end
+
+        band = Band.new
+        band.albums?
+        band.has_albums?
+        band.label?
+        band.has_label?
+
+* \#1188 1-1 relations now have an :autobuild option to indicate if the
+  relation should automatically be build with empty attributes upon access
+  where the relation currently does not exist. Works on embeds_one,
+  embedded_in, has_one, belongs_to. (Andy Morris)
+
+        class Band
+          include Mongoid::Document
+          has_one :label, autobuild: true
+        end
+
+        band = Band.new
+        band.label # Returns a new label with empty attributes.
+
+      When using existence checks, autobuilding will not execute.
+
+        band = Band.new
+        band.label? # Returns false, does not autobuild on a check.
+        band.has_label? # Returns false, does not autobuild on a check.
+
+* \#1081 Mongoid indexes both id and type as a compound index when providing
+  `index: true` to a polymorphic belongs_to.
+
+        class Comment
+          include Mongoid::Document
+
+          # Indexes commentable_id and commentable_type as a compound index.
+          belongs_to :commentable, polymorphic: true, index: true
+        end
+
+* \#1053 Raise a `Mongoid::Errors::UnknownAttribute` instead of no method
+  when attempting to set a field that is not defined and allow dynamic
+  fields is false. (Cyril Mougel)
+
+        Mongoid.allow_dynamic_fields = false
+
+        class Person
+          include Mongoid::Document
+          field :title, type: String
+        end
+
+        Person.new.age = 50 # raises the UnknownAttribute error.
+
+* \#772 Fields can now be flagged as readonly, which will only let their
+  values be set when the document is new.
+
+        class Band
+          include Mongoid::Document
+          field :name, type: String
+          field :genre, type: String
+
+          attr_readonly :name, :genre
+        end
+
+      Readonly values are ignored when attempting to set them on persisted
+      documents, with the exception of update_attribute and remove_attribute,
+      where errors will get raised.
+
+        band = Band.create(name: "Depeche Mode")
+        band.update_attribute(:name, "Smiths") # Raises ReadonlyAttribute error.
+        band.remove_attribute(:name) # Raises ReadonlyAttribute error.
+
+
+### Major Changes (Backwards Incompatible)
+
+* Polymorphic relations can not have ids other than object ids. This is
+  because Mongoid cannot properly figure out in an optimized way what the
+  various classes on the other side of the relation store their ids as, as
+  they could potentially all be different.
+
+  This was not allowed before, but nowhere was it explicitly stated.
+
+* \#2039 Validating presence of a relation now checks both the relation and
+  the foreign key value.
+
+* Indexing syntax has changed. The first parameter is now a hash of
+  name/direction pairs with an optional second hash parameter for
+  additional options.
+
+      Normal indexing with options, directions are either 1 or -1:
+
+        class Band
+          include Mongoid::Document
+          field :name, type: String
+
+          index({ name: 1 }, { unique: true, background: true })
+        end
+
+      Geospacial indexing needs "2d" as it's direction.
+
+        class Venue
+          include Mongoid::Document
+          field :location, type: Array
+
+          index location: "2d"
+        end
+
+* Custom serializable fields have revamped. Your object no longer should
+  include `Mongoid::Fields::Serializable` - instead it only needs to
+  implement 3 methods: `#mongoize`, `.demongoize` and `.evolve`.
+
+      `#mongoize` is an instance method that transforms your object into
+      a mongo-friendly value.
+
+      `.demongoize` is a class method, that can take some data from mongo
+      and instantiate and object of your custom type.
+
+      `.evolve` is a class method, that can take any object, and
+      transform it for use in a `Mongoid::Criteria`.
+
+      An example of an implementation of this for `Range`:
+
+        class Range
+
+          def mongoize
+            { "min" => first, "max" => last }
+          end
+
+          class << self
+
+            def demongoize(object)
+              Range.new(object["min"], object["max"])
+            end
+
+            def evolve(object)
+              { "$gte" => object.first, "$lte" => object.last }
+            end
+          end
+        end
+
+* `Document#changes` is no longer a hash with indifferent access.
+
+* `after_initialize` callbacks no longer cascade to children if the option
+  is set.
+
+* \#1865 `count` on the memory and mongo contexts now behave exactly the
+  same as Ruby's `count` on enumerable, and can take an object or a block.
+  This is optimized on the mongo context not to load everything in memory
+  with the exception of passing a block.
+
+        Band.where(name: "Tool").count
+        Band.where(name: "Tool").count(tool) # redundant.
+        Band.where(name: "Tool") do |doc|
+          doc.likes > 0
+        end
+
+    Note that although the signatures are the same for both the memory and
+    mongo contexts, it's recommended you only use the block syntax for the
+    memory context since the embedded documents are already loaded into
+    memory.
+
+    Also note that passing a boolean to take skip and limit into account
+    is no longer supported, as this is not necessarily a useful feature.
+
+* The `autocreate_indexes` configuration option has been removed.
+
+* `Model.defaults` no longer exists. You may get all defaults with a
+  combination of `Model.pre_processed_defaults` and
+  `Model.post_processed_defaults`.
+
+        Band.pre_processed_defaults
+        Band.post_processed_defaults
+
+* `Model.identity` and `Model.key` have been removed. For custom ids,
+  users must now override the _id field.
+
+    When the default value is a proc, the default is applied *after* all
+    other attributes are set.
+
+        class Band
+          include Mongoid::Document
+          field :_id, type: String, default: ->{ name }
+        end
+
+    To have the default applied *before* other attributes, set `:pre_processed`
+    to true.
+
+        class Band
+          include Mongoid::Document
+          field :_id,
+            type: String,
+            pre_processed: true,
+            default: ->{ BSON::ObjectId.new.to_s }
+        end
+
+* Custom application exceptions in various languages has been removed,
+  along with the `Mongoid.add_language` feature.
+
+* Mongoid no longer supports 1.8. MRI 1.9.3 and higher, or JRuby 1.6 and
+  higher in 1.9 mode are only supported.
+
+* \#1734 When searching for documents via `Model.find` with multiple ids,
+  Mongoid will raise an error if not *all* ids are found, and tell you
+  what the missing ones were. Previously the error only got raised if
+  nothing was returned.
+
+* \#1675 Adding presence validation on a relation now enables autosave.
+  This is to ensure that when a new parent object is saved with a new
+  child and marked is valid, both are persisted to ensure a correct
+  state in the database.
+
+* \#1491 Ensure empty translations returns an empty hash on access.
+
+* \#1484 `Model#has_attribute?` now behaves the same as Active Record.
+
+* \#1471 Mongoid no longer strips any level of precision off of times.
+
+* \#1475 Active support's time zone is now used by default in time
+  serialization if it is defined.
+
+* \#1342 `Model.find` and `model.relation.find` now only take a single or
+  multiple ids. The first/last/all with a conditions hash has been removed.
+
+* \#1291 The mongoid.yml has been revamped completely, and upgrading
+  existing applications will greet you with some lovely Mongoid specific
+  configuration errors. You can re-generate a new mongoid.yml via the
+  existing rake task, which is commented to an insane degree to help you
+  with all the configuration possibilities.
+
+* \#1291 The `persist_in_safe_mode` configuration option has been removed.
+  You must now tell a database session in the mongoid.yml whether or not
+  it should persist in safe mode by default.
+
+        production:
+          sessions:
+            default:
+              database: my_app_prod
+              hosts:
+                - db.app.com:27018
+                - db.app.com:27019
+              options:
+                consistency: :eventual
+                safe: true
+
+* \#1291 `safely` and `unsafely` have been removed. Please now use `with`
+  to provide safe mode options at runtime.
+
+        Band.with(safe: true).create
+        band.with(safe: { w: 3 }).save!
+        Band.with(safe: false).create!
+
+* \#1270 Relation macros have been changed to match their AR counterparts:
+  only :has_one, :has_many, :has_and_belongs_to_many, and :belongs_to
+  exist now.
+
+* \#1268 `Model#new?` has been removed, developers must now always use
+  `Model#new_record?`.
+
+* \#1182 A reload is no longer required to refresh a relation after setting
+  the value of the foreign key field for it. Note this behaves exactly as
+  Active Record.
+
+    If the id is set, but the document for it has not been persisted, accessing
+    the relation will return empty results.
+
+    If the id is set and it's document is persisted, accessing the relation
+    will return the document.
+
+    If the id is set, but the base document is not saved afterwards, then
+    reloading will return the document to it's original state.
+
+* \#1093 Field serialization strategies have changed on Array, Hash, Integer
+  and Boolean to be more consistent and match AR where appropriate.
+
+    Serialization of arrays calls `Array.wrap(object)`
+    Serialization of hashes calls `Hash[object]` (to_hash on the object)
+    Serialization of integers always returns an int via `to_i`
+    Serialization of booleans defaults to false instead of nil.
+
+* \#933 `:field.size` has been renamed to `:field.count` in criteria for
+  $size not to conflict with Symbol's size method.
+
+* \#829/\#797 Mongoid scoping code has been completely rewritten, and now
+  matches the Active Record API. With this backwards incompatible change,
+  some methods have been removed or renamed.
+
+    Criteria#as_conditions and Criteria#fuse no longer exist.
+
+    Criteria#merge now only accepts another object that responds to
+    `to_criteria`.
+
+    Criteria#merge! now merges in another object without creating a new
+    criteria object.
+
+        Band.where(name: "Tool").merge!(criteria)
+
+    Named scopes and default scopes no longer take hashes as parameters.
+    From now on only criteria and procs wrapping criteria will be
+    accepted, and an error will be raised if the arguments are incorrect.
+
+        class Band
+          include Mongoid::Document
+
+          default_scope ->{ where(active: true) }
+          scope :inactive, where(active: false)
+          scope :invalid, where: { valid: false } # This will raise an error.
+        end
+
+    The 'named_scope' macro has been removed, from now on only use 'scope'.
+
+    Model.unscoped now accepts a block which will not allow default scoping
+    to be applied for any calls inside the block.
+
+        Band.unscoped do
+          Band.scoped.where(name: "Ministry")
+        end
+
+    Model.scoped now takes options that will be set directly on the criteria
+    options hash.
+
+        Band.scoped(skip: 10, limit: 20)
+
+* \#463 `Document#upsert` is no longer aliased to `Document#save` and now
+  actually performs a proper MongoDB upsert command when called. If you
+  were using this method before and want the same behaviour, please switch
+  to `save`.
+
+        band = Band.new(name: "Tool")
+        band.upsert #=> Inserts the document in the database.
+        band.name = "Placebo"
+        band.upsert #=> Updates the existing document.
 
 ### Resolved Issues
 
+* \#2166 `Criteria#from_map_or_db` strips type selection when eager loading
+  since it will check if the type is correct after.
+
+* \#2129 Fixed sorting for all fields on embeds many relations.
+
+* \#2124 Fixed default scope and deleted scope on paranoid documents.
+
+* \#2122 Allow embedded documents to sort on boolean fields.
+
+* \#2119 Allow `Criteria#update_all` to accept atomic ops and normal sets.
+
+* \#2118 Don't strip any precision during `DateTime` -> `Time` conversions.
+
+* \#2117 Ensure embeds one relations have callbacks run when using nested
+  attributes.
+
+* \#2110 `Model#touch` now works properly on embedded documents.
+
+* \#2100 Allow atomic operations to properly execute on paranoid documents
+  that have a deleted_at set.
+
+* \#2089 Allow proper separation of mongoization and evolving with respect to
+  foreign keys.
+
+* \#2088 Allow finds by string ids to pull from the identity map if the ids
+  are stored as object ids.
+
+* \#2085 Allow demongoization of floats and ints to big decimals.
+
+* \#2084 Don't cascade if metadata does not exist.
+
+* \#2078 Calling `Model#clone` or `Model#dup` now properly sets attributes
+  as dirty.
+
+* \#2070 Allow for updated_at to be overridden manually for new documents that
+  also have a created_at.
+
+* \#2041 Don't hit the database multiple times on relation access after an
+  eager load returned zero documents.
+
+* \#1997 Cascading callbacks should be able to halt the callback chain when
+  terminating.
+
+* \#1972 `added`, `loaded`, and `unloaded` can now be valid scope names on a
+  document that is part of a 1-n relation.
+
+* \#1952/#1950 `#all_in` behaviour on embedded documents now properly matches
+  root documents when passing an empty array. (Hans Hasselberg)
+
+* \#1941/#1939 `Model.find_by` now returns nil if raise not found error is
+  set to false. (Hans Hasselberg)
+
+* \#1859/#1860 `Model#remove_attribute` now properly unsets on embedded
+  documents. (Anton Onyshchenko)
+
+* \#1852 Ensure no infinite recursion on cascading callbacks. (Ara Howard)
+
+* \#1823 `Relation#includes?` now properly works with identity map enabled.
+
+* \#1810 `Model#changed?` no longer returns true when hash and array fields
+  have only been accessed.
+
+* \#1876/\#1782 Allow dot notation in embeds many criteria queries.
+  (Cyril Mougel)
+
+* \#1745 Fixed batch clear to work within attribute setting.
+
+* \#1718 Ensure consistency of #first/#last in relations - they now always
+  match first/last in the database, but opts for in memory first.
+
+* \#1692/\#1376 `Model#updateattributes` and `Model#update_attributes!` now
+  accept assignment options. (Hans Hasselberg)
+
+* \#1688/\#1207 Don't require namespacing when providing class name on
+  relation macros inside the namespace. (Hans Hasselberg)
+
+* \#1665/\#1672 Expand complex criteria in nested criteria selectors, like
+  \#matches. (Hans Hasselberg)
+
+* \#1335 Don't add id sorting criteria to first/last is there is already
+  sorting options on the criteria.
+
+* \#1321 Referenced many enumerable targets are now hash-backed, preventing
+  duplicates in a more efficient manner.
+
+* \#1135 DateTimes now properly get time zones on deserialization.
+
+* \#1031 Mongoid now serializes values in Array fields to their proper
+  Mongo-friendly values when possible.
+
+* \#685 Attempting to use versioning with embedded documents will now
+  raise a proper error alerting the developer this is not allowed.
+
+## 2.4.12 (branch: 2.4.0-stable)
+
+### Resolved Issues
+
+* \#2144 Uniqueness validation on paranoid documents now properly scopes.
+
+* \#2127 Don't unbind parents of embedded documents mid nested
+  attributes deletion.
+
+## 2.4.11
+
+### Resolved Issues
+
+* This release forces a cap on the mongo driver version at 1.6.2 due to
+  changes in the `Mongo::Connection.from_uri` API not allowing valid
+  connection options anymore.
+
+* \#2040 Fixed bad interpolation for locale presence validation.
+
+* \#2038 Allow inverse relations to be determined by foreign keys alone
+  if defined on both sides, not just an inverse_of declaration.
+
+* \#2023 Allow serilialization of dynamic types that conflict with core
+  Ruby methods to still be serialized.
+
+* \#2008 Presence validation should hit the db to check validity if the
+  relation in memory is blank.
+
+* \#2006 Allow excluding only the _id field post execution of an #only call.
+
 ## 2.4.10
 
 ### Resolved Issues
@@ -23,8 +958,6 @@ For instructions on upgrading to newer versions, visit
 * \#1987 Don't double-insert documents into identity map when eager loading
   twice inside the unit of work.
 
-* \#1976 Don't execute eager load queries when base query is empty.
-
 * \#1953 Uniqueness validation now works on localized fields.
 
 * \#1936 Allow setting n levels deep embedded documents atomically without
@@ -66,7 +999,7 @@ For instructions on upgrading to newer versions, visit
 * \#1916/\#1913 Uniqueness validation no longer is affected by the default
   scope. (Hans Hasselberg)
 
-* \#1778 Ensure foreign keys are always set regardless of binding state.
+* \#1943 Ensure numericality validation works for big decimals.
 
 ## 2.4.8
 
@@ -177,8 +1110,8 @@ For instructions on upgrading to newer versions, visit
 
 * \#1676 Allow eager loading to work as a default scope.
 
-* \#1665/#1672 Expand complex criteria in nested criteria selectors, like
-  #matches. (Hans Hasselberg)
+* \#1665/\#1672 Expand complex criteria in nested criteria selectors, like
+  \#matches. (Hans Hasselberg)
 
 * \#1668 Ensure Mongoid logger exists before calling warn. (Rémy Coutable)
 
@@ -186,10 +1119,10 @@ For instructions on upgrading to newer versions, visit
 
 * \#1659 Clear delayed atomic sets when resetting the same embedded relation.
 
-* \#1656/#1657 Don't hit database for uniqueness validation if BOTH scope
+* \#1656/\#1657 Don't hit database for uniqueness validation if BOTH scope
   and attribute hasn't changed. (priyaaank)
 
-* \#1205/#1642 When limiting fields returned from the database via
+* \#1205/\#1642 When limiting fields returned from the database via
   `Criteria#only` and `Criteria#without` and then subsequently saving
   the document. Default values no longer override excluded fields.
 
@@ -200,16 +1133,18 @@ For instructions on upgrading to newer versions, visit
 * \#1647 DateTime serialization when already in UTC does not convert to
   local time.
 
+* \#1641/\#1639 Mongoid.observer.disable :all now behaves as AR does.
+
 * \#1640 Update consumers should be tied to the name of the collection
   they persist to, not the name of the class.
 
-* \#1636 Scopes no longer modify parent class scopes when subclassing.
+* \#1637/\#1636 Scopes no longer modify parent class scopes when subclassing.
   (Hans Hasselberg)
 
 * \#1629 $all and $in criteria on embedded many relations now properly
   handles regex searches and elements of varying length. (Douwe Maan)
 
-* \#1623 Default scopes no longer break Mongoid::Versioning.
+* \#1623/\#1634 Default scopes no longer break Mongoid::Versioning.
   (Hans Hasselberg)
 
 * \#1605 Fix regression of rescue responses, Rails 3.2
@@ -218,6 +1153,10 @@ For instructions on upgrading to newer versions, visit
 
 ### Resolved Issues
 
+* \#1628 _type field can once again be included in serialization to json
+  or xml as a global option with `include_type_for_serialization`.
+  (Roman Shterenzon)
+
 * \#1627 Validating format now works properly with localized fields.
   (Douwe Maan)