<commit_before># Overview

For instructions on upgrading to newer versions, visit
[mongoid.org](http://mongoid.org/docs/upgrading.html).

## 3.0.0 (branch: master)

### New Features

* \#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.
  (<NAME>)

        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.face = 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. (<NAME>)

        Band.find_by(name: "<NAME>")

* \#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.safely.push(album)
        band.albums.safely.create(name: "Smiths")

        album.safely.create_producer(name: "Flood")

* \#1348 Eager loading is now supported on many-to-many relations.

* \#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. (<NAME>)

        Mongoid.allow_dynamic_fields = false

        class Person
          include Mongoid::Document
          field :title, type: String
        end

        Person.new.age = 50 # raises the UnknownAttribute error.

### Major Changes

* `Model.defaults` no longer exists. You may get all defaults with a
  combination of `Model.pre_processed_defaults` and
  `Model.post_processed_defaults`

* `Model.identity` and `Model.key` have been removed. For custome ids,
  users must now override the _id field like so:
  `field :_id, type: String, default: ->{ name }`.

* Custom application exceptions in various languages has been removed,
  along with the `Mongoid.add_language` feature.

* Mongoid no longer supports 1.8 syntax. 1.9.x or other vms running in
  1.9 mode is now only supported.

* \#1484 `Model#has_attribute?` now behaves the same as Active Record.<commit_msg>Update changelog for new field overriding<commit_after># Overview

For instructions on upgrading to newer versions, visit
[mongoid.org](http://mongoid.org/docs/upgrading.html).

## 3.0.0 (branch: master)

### New Features

* \#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.
  (<NAME>)

        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.face = 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. (<NAME>)

        Band.find_by(name: "<NAME>")

* \#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.safely.push(album)
        band.albums.safely.create(name: "Smiths")

        album.safely.create_producer(name: "Flood")

* \#1348 Eager loading is now supported on many-to-many relations.

* \#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. (<NAME>)

        Mongoid.allow_dynamic_fields = false

        class Person
          include Mongoid::Document
          field :title, type: String
        end

        Person.new.age = 50 # raises the UnknownAttribute error.

### Major Changes

* `Model.defaults` no longer exists. You may get all defaults with a
  combination of `Model.pre_processed_defaults` and
  `Model.post_processed_defaults`

* `Model.identity` and `Model.key` have been removed. For custome 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 syntax. 1.9.x or other vms running in
  1.9 mode is now only supported.

* \#1484 `Model#has_attribute?` now behaves the same as Active Record.
{'fraction_non_alphanumeric': 0.06533264922182316, 'fraction_numerical': 0.014024285958611254, 'mean_word_length': 2.4356639247943597, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 14, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6832130', 'n_tokens_mistral': 3349, 'n_tokens_neox': 3116, 'n_words': 1273}