mongoid-history 0.4.1 → 0.4.2

data/CONTRIBUTING.md

@@ -0,0 +1,118 @@
+Contributing to Mongoid-History
+===============================
+
+Mongoid-History is work of [many of contributors](https://github.com/intridea/mongoid-history/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/intridea/mongoid-history/pulls), [propose features, ask questions and discuss issues](https://github.com/intridea/mongoid-history/issues).
+
+#### Fork the Project
+
+Fork the [project on Github](https://github.com/intridea/mongoid-history) and check out your copy.
+
+```
+git clone https://github.com/contributor/mongoid-history.git
+cd mongoid-history
+git remote add upstream https://github.com/intridea/mongoid-history.git
+```
+
+#### Create a Topic Branch
+
+Make sure your fork is up-to-date and create a topic branch for your feature or bug fix.
+
+```
+git checkout master
+git pull upstream master
+git checkout -b my-feature-branch
+```
+
+#### Bundle Install and Test
+
+Ensure that you can build the project and run tests.
+
+```
+bundle install
+bundle exec rake
+```
+
+#### Write Tests
+
+Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build. Add to [spec/mongoid-history](spec/mongoid-history).
+
+We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.
+
+#### Write Code
+
+Implement your feature or bug fix.
+
+Ruby style is enforced with [Rubocop](https://github.com/bbatsov/rubocop), run `bundle exec rubocop` and fix any style issues highlighted.
+
+Make sure that `bundle exec rake` completes without errors.
+
+#### Write Documentation
+
+Document any external behavior in the [README](README.md).
+
+#### Update Changelog
+
+Add a line to [CHANGELOG](CHANGELOG.md) under *Next Release*. Make it look like every other line, including your name and link to your Github account.
+
+#### Commit Changes
+
+Make sure git knows your name and email address:
+
+```
+git config --global user.name "Your Name"
+git config --global user.email "contributor@example.com"
+```
+
+Writing good commit logs is important. A commit log should describe what changed and why.
+
+```
+git add ...
+git commit
+```
+
+#### Push
+
+```
+git push origin my-feature-branch
+```
+
+#### Make a Pull Request
+
+Go to https://github.com/contributor/mongoid-history and select your feature branch. Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days.
+
+#### Rebase
+
+If you've been working on a change for a while, rebase with upstream/master.
+
+```
+git fetch upstream
+git rebase upstream/master
+git push origin my-feature-branch -f
+```
+
+#### Update CHANGELOG Again
+
+Update the [CHANGELOG](CHANGELOG.md) with the pull request number. A typical entry looks as follows.
+
+```
+* [#123](https://github.com/intridea/mongoid-history/pull/123): Reticulated splines - [@contributor](https://github.com/contributor).
+```
+
+Amend your previous commit and force push the changes.
+
+```
+git commit --amend
+git push origin my-feature-branch -f
+```
+
+#### Check on Your Pull Request
+
+Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI. Everything should look green, otherwise fix issues and amend your commit as described above.
+
+#### Be Patient
+
+It's likely that your change will not be merged and that the nitpicky maintainers will ask you to do more, or fix seemingly benign problems. Hang on there!
+
+#### Thank You
+
+Please do know that we really appreciate and value your time and work. We love you, really.

data/Gemfile

@@ -1,16 +1,12 @@
-source "http://rubygems.org"
-
-gem "easy_diff"
-gem "mongoid", ">= 3.0"
-gem "activesupport"
-
-group :test do
-  gem "rspec", ">= 2.11.0"
-  gem "bundler", ">= 1.0.0"
-end
-
-group :development do
-  gem 'rubocop', '~> 0.15.0'
-  gem "yard"
-  gem "jeweler"
-end
+source 'https://rubygems.org'
+
+gemspec
+
+case version = ENV['MONGOID_VERSION'] || '~> 4.0'
+when /4/
+  gem 'mongoid', '~> 4.0'
+when /3/
+  gem 'mongoid', '~> 3.1'
+else
+  gem 'mongoid', version
+end

data/LICENSE.txt

@@ -1,20 +1,20 @@
-Copyright (c) 2011 Aaron Qian
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2011 Aaron Qian
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,309 +1,312 @@
-mongoid-history
-===============
-
-[![Build Status](https://secure.travis-ci.org/aq1018/mongoid-history.png?branch=master)](http://travis-ci.org/aq1018/mongoid-history)
-[![Code Climate](https://codeclimate.com/github/aq1018/mongoid-history.png)](https://codeclimate.com/github/aq1018/mongoid-history)
-
-Mongoid-history tracks historical changes for any document, including embedded ones. It achieves this by storing all history tracks in a single collection that you define. Embedded documents are referenced by storing an association path, which is an array of `document_name` and `document_id` fields starting from the top most parent document and down to the embedded document that should track history.
-
-This gem also implements multi-user undo, which allows users to undo any history change in any order. Undoing a document also creates a new history track. This is great for auditing and preventing vandalism, but is probably not suitable for use cases such as a wiki.
-
-Stable Release
---------------
-
-You're reading the documentation the 0.4.x release that supports Mongoid 3.x. For 2.x compatible mongoid-history, please use a 0.2.x version from the [2.x-stable branch](https://github.com/aq1018/mongoid-history/tree/2.4-stable).
-
-Install
--------
-
-This gem supports Mongoid 3.x on Ruby 1.9.3 only. Add it to your `Gemfile` or run `gem install mongoid-history`.
-
-```ruby
-gem 'mongoid-history'
-```
-
-Usage
------
-
-**Create a history tracker**
-
-Create a new class to track histories. All histories are stored in this tracker. The name of the class can be anything you like. The only requirement is that it includes `Mongoid::History::Tracker`
-
-```ruby
-# app/models/history_tracker.rb
-class HistoryTracker
-  include Mongoid::History::Tracker
-end
-```
-
-**Set tracker class name**
-
-Manually set the tracker class name to make sure your tracker can be found and loaded properly. You can skip this step if you manually require your tracker before using any trackables.
-
-The following example sets the tracker class name using a Rails initializer.
-
-```ruby
-# config/initializers/mongoid-history.rb
-# initializer for mongoid-history
-# assuming HistoryTracker is your tracker class
-Mongoid::History.tracker_class_name = :history_tracker
-```
-
-**Create trackable classes and objects**
-
-```ruby
-class Post
-  include Mongoid::Document
-  include Mongoid::Timestamps
-
-  # history tracking all Post documents
-  # note: tracking will not work until #track_history is invoked
-  include Mongoid::History::Trackable
-
-  field           :title
-  field           :body
-  field           :rating
-  embeds_many     :comments
-
-  # telling Mongoid::History how you want to track changes
-  track_history   :on => [:title, :body],       # track title and body fields only, default is :all
-                  :modifier_field => :modifier, # adds "belongs_to :modifier" to track who made the change, default is :modifier
-                  :modifier_field_inverse_of => :nil, # adds an ":inverse_of" option to the "belongs_to :modifier" relation, default is not set
-                  :version_field => :version,   # adds "field :version, :type => Integer" to track current version, default is :version
-                  :track_create   =>  false,    # track document creation, default is false
-                  :track_update   =>  true,     # track document updates, default is true
-                  :track_destroy  =>  false     # track document destruction, default is false
-end
-
-class Comment
-  include Mongoid::Document
-  include Mongoid::Timestamps
-
-  # declare that we want to track comments
-  include Mongoid::History::Trackable
-
-  field             :title
-  field             :body
-  embedded_in       :post, :inverse_of => :comments
-
-  # track title and body for all comments, scope it to post (the parent)
-  # also track creation and destruction
-  track_history     :on => [:title, :body], :scope => :post, :track_create => true, :track_destroy => true
-end
-
-# the modifier class
-class User
-  include Mongoid::Document
-  include Mongoid::Timestamps
-
-  field             :name
-end
-
-user = User.create(:name => "Aaron")
-post = Post.create(:title => "Test", :body => "Post", :modifier => user)
-comment = post.comments.create(:title => "test", :body => "comment", :modifier => user)
-comment.history_tracks.count # should be 1
-
-comment.update_attributes(:title => "Test 2")
-comment.history_tracks.count # should be 2
-
-track = comment.history_tracks.last
-
-track.undo! user # comment title should be "Test"
-
-track.redo! user # comment title should be "Test 2"
-
-# undo last change
-comment.undo! user
-
-# undo versions 1 - 4
-comment.undo! user, :from => 4, :to => 1
-
-# undo last 3 versions
-comment.undo! user, :last => 3
-
-# redo versions 1 - 4
-comment.redo! user, :from => 1, :to => 4
-
-# redo last 3 versions
-comment.redo! user, :last => 3
-
-# redo version 1
-comment.redo! user, 1
-
-# delete post
-post.destroy
-
-# undelete post
-post.undo! user
-
-# disable tracking for comments within a block
-Comment.disable_tracking do
-  comment.update_attributes(:title => "Test 3")
-end
-
-# globally disable all history tracking
-Mongoid::History.disable do
-  comment.update_attributes(:title => "Test 3")
-  user.update_attributes(:name => "Eddie Van Halen")
-end
-```
-
-**Retrieving the list of tracked fields**
-
-```ruby
-class Book
-  ...
-  field             :title
-  field             :author
-  field             :price
-  track_history     :on => [:title, :price]
-end
-
-Book.tracked_fields           #=> ["title", "price"]
-Book.tracked_field?(:title)   #=> true
-Book.tracked_field?(:author)  #=> false
-```
-
-**Displaying history trackers as an audit trail**
-
-In your Controller:
-
-```ruby
-# Fetch history trackers
-@trackers = HistoryTracker.limit(25)
-
-# get change set for the first tracker
-@changes = @trackers.first.tracked_changes
-  #=> {field: {to: val1, from: val2}}
-
-# get edit set for the first tracker
-@edits = @trackers.first.tracked_edits
-  #=> { add: {field: val},
-  #     remove: {field: val},
-  #     modify: { to: val1, from: val2 },
-  #     array: { add: [val2], remove: [val1] } }
-```
-
-In your View, you might do something like (example in HAML format):
-
-```haml
-%ul.changes
-  - (@edits[:add]||[]).each do |k,v|
-    %li.remove Added field #{k} value #{v}
-
-  - (@edits[:modify]||[]).each do |k,v|
-    %li.modify Changed field #{k} from #{v[:from]} to #{v[:to]}
-
-  - (@edits[:array]||[]).each do |k,v|
-    %li.modify
-      - if v[:remove].nil?
-        Changed field #{k} by adding #{v[:add]}
-      - elsif v[:add].nil?
-        Changed field #{k} by removing #{v[:remove]}
-      - else
-        Changed field #{k} by adding #{v[:add]} and removing #{v[:remove]}
-
-  - (@edits[:remove]||[]).each do |k,v|
-    %li.remove Removed field #{k} (was previously #{v})
-```
-
-**Adding Userstamp on History Trackers**
-
-To track the User in the application who created the HistoryTracker, please add the 
-[Mongoid::Userstamp gem](https://github.com/tbpro/mongoid_userstamp) to your HistoryTracker class.
-This will add a field called `created_by` and an accessor `creator` to the model (you can rename these via gem config). 
-
-```
-class MyHistoryTracker
-  include Mongoid::History::Tracker
-  include Mongoid::Userstamp
-end
-```
-
-*Migrating Userstamp from Previous Versions*
-
-Since October 2013, Mongoid::History itself no longer supports the userstamp natively. In order to migrate, follow the 
-instructions above then run the following command:
-
-```
-MyHistoryTracker.all.each{|ht| ht.rename(:modifier_id, :created_by)
-```
-
-**Using an alternate changes method**
-
-Sometimes you may wish to provide an alternate method for determining which changes should be tracked.  For example, if you are using embedded documents
-and nested attributes, you may wish to write your own changes method that includes changes from the embedded documents.
-
-Mongoid::History provides an option named `:changes_method` which allows you to do this.  It defaults to `:changes`, which is the standard changes method.
-
-Example:
-
-```ruby
-class Foo
-  include Mongoid::Document
-  include Mongoid::Timestamps
-  include Mongoid::History::Trackable
-
-  field      :bar
-  embeds_one :baz
-  accepts_nested_attributes_for :baz
-
-  # use changes_with_baz to include baz's changes in this document's
-  # history.
-  track_history     :changes_method => :changes_with_baz
-
-  def changes_with_baz
-    if baz.changed?
-      changes.merge( :baz => summarized_changes(baz) )
-    else
-      changes
-    end
-  end
-
-  private
-  # This method takes the changes from an embedded doc and formats them
-  # in a summarized way, similar to how the embedded doc appears in the
-  # parent document's attributes
-  def summarized_changes obj
-    obj.changes.keys.map do |field|
-      next unless obj.respond_to?("#{field}_change")
-      [ { field => obj.send("#{field}_change")[0] },
-        { field => obj.send("#{field}_change")[1] } ]
-    end.compact.transpose.map do |fields|
-      fields.inject({}) {|map,f| map.merge(f)}
-    end
-  end
-end
-
-class Baz
-  include Mongoid::Document
-  include Mongoid::Timestamps
-
-  embedded_in :foo
-  field :value
-end
-```
-
-For more examples, check out [spec/integration/integration_spec.rb](https://github.com/aq1018/mongoid-history/blob/master/spec/integration/integration_spec.rb).
-
-Contributing to mongoid-history
--------------------------------
-
-* Check out the latest code to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
-* Fork the project.
-* Create a feature/bugfix branch.
-* Commit and push until you are happy with your changes.
-* Make sure to add tests.
-* Update the CHANGELOG for the next release.
-* Try not to mess with the Rakefile or version.
-* Make a pull request.
-
-Copyright
----------
-
-Copyright (c) 2011-2012 Aaron Qian. MIT License.
-
-See [LICENSE.txt](https://github.com/aq1018/mongoid-history/blob/master/LICENSE.txt) for further details.
-
+mongoid-history
+===============
+
+[![Gem Version](https://badge.fury.io/rb/mongoid-history.png)](http://badge.fury.io/rb/mongoid-history)
+[![Build Status](https://secure.travis-ci.org/aq1018/mongoid-history.png?branch=master)](http://travis-ci.org/aq1018/mongoid-history)
+[![Dependency Status](https://gemnasium.com/aq1018/mongoid-history.png)](https://gemnasium.com/aq1018/mongoid-history)
+[![Code Climate](https://codeclimate.com/github/aq1018/mongoid-history.png)](https://codeclimate.com/github/aq1018/mongoid-history)
+[![Coverage Status](https://coveralls.io/repos/aq1018/mongoid-history/badge.png?branch=coveralls)](https://coveralls.io/r/aq1018/mongoid-history?branch=coveralls)
+
+Mongoid-history tracks historical changes for any document, including embedded ones. It achieves this by storing all history tracks in a single collection that you define. Embedded documents are referenced by storing an association path, which is an array of `document_name` and `document_id` fields starting from the top most parent document and down to the embedded document that should track history.
+
+This gem also implements multi-user undo, which allows users to undo any history change in any order. Undoing a document also creates a new history track. This is great for auditing and preventing vandalism, but is probably not suitable for use cases such as a wiki (but we won't stop you either).
+
+Stable Release
+--------------
+
+You're reading the documentation the 0.4.x release that supports Mongoid 3.x and 4.x. For 2.x compatible mongoid-history, please use a 0.2.x version from the [2.x-stable branch](https://github.com/aq1018/mongoid-history/tree/2.4-stable).
+
+Install
+-------
+
+This gem supports Mongoid 3.x and 4.x on Ruby 1.9.3 or newer. Add it to your `Gemfile` or run `gem install mongoid-history`.
+
+```ruby
+gem 'mongoid-history'
+```
+
+Usage
+-----
+
+**Create a history tracker**
+
+Create a new class to track histories. All histories are stored in this tracker. The name of the class can be anything you like. The only requirement is that it includes `Mongoid::History::Tracker`
+
+```ruby
+# app/models/history_tracker.rb
+class HistoryTracker
+  include Mongoid::History::Tracker
+end
+```
+
+**Set tracker class name**
+
+Manually set the tracker class name to make sure your tracker can be found and loaded properly. You can skip this step if you manually require your tracker before using any trackables.
+
+The following example sets the tracker class name using a Rails initializer.
+
+```ruby
+# config/initializers/mongoid-history.rb
+# initializer for mongoid-history
+# assuming HistoryTracker is your tracker class
+Mongoid::History.tracker_class_name = :history_tracker
+```
+
+**Create trackable classes and objects**
+
+```ruby
+class Post
+  include Mongoid::Document
+  include Mongoid::Timestamps
+
+  # history tracking all Post documents
+  # note: tracking will not work until #track_history is invoked
+  include Mongoid::History::Trackable
+
+  field           :title
+  field           :body
+  field           :rating
+  embeds_many     :comments
+
+  # telling Mongoid::History how you want to track changes
+  track_history   :on => [:title, :body],       # track title and body fields only, default is :all
+                  :modifier_field => :modifier, # adds "belongs_to :modifier" to track who made the change, default is :modifier
+                  :modifier_field_inverse_of => :nil, # adds an ":inverse_of" option to the "belongs_to :modifier" relation, default is not set
+                  :version_field => :version,   # adds "field :version, :type => Integer" to track current version, default is :version
+                  :track_create   =>  false,    # track document creation, default is false
+                  :track_update   =>  true,     # track document updates, default is true
+                  :track_destroy  =>  false     # track document destruction, default is false
+end
+
+class Comment
+  include Mongoid::Document
+  include Mongoid::Timestamps
+
+  # declare that we want to track comments
+  include Mongoid::History::Trackable
+
+  field             :title
+  field             :body
+  embedded_in       :post, :inverse_of => :comments
+
+  # track title and body for all comments, scope it to post (the parent)
+  # also track creation and destruction
+  track_history     :on => [:title, :body], :scope => :post, :track_create => true, :track_destroy => true
+
+  # For embedded polymorphic relations, specify an array of model names or its polymorphic name
+  # e.g. :scope => [:post, :image, :video]
+  #      :scope => :commentable
+
+end
+
+# the modifier class
+class User
+  include Mongoid::Document
+  include Mongoid::Timestamps
+
+  field             :name
+end
+
+user = User.create(:name => "Aaron")
+post = Post.create(:title => "Test", :body => "Post", :modifier => user)
+comment = post.comments.create(:title => "test", :body => "comment", :modifier => user)
+comment.history_tracks.count # should be 1
+
+comment.update_attributes(:title => "Test 2")
+comment.history_tracks.count # should be 2
+
+track = comment.history_tracks.last
+
+track.undo! user # comment title should be "Test"
+
+track.redo! user # comment title should be "Test 2"
+
+# undo last change
+comment.undo! user
+
+# undo versions 1 - 4
+comment.undo! user, :from => 4, :to => 1
+
+# undo last 3 versions
+comment.undo! user, :last => 3
+
+# redo versions 1 - 4
+comment.redo! user, :from => 1, :to => 4
+
+# redo last 3 versions
+comment.redo! user, :last => 3
+
+# redo version 1
+comment.redo! user, 1
+
+# delete post
+post.destroy
+
+# undelete post
+post.undo! user
+
+# disable tracking for comments within a block
+Comment.disable_tracking do
+  comment.update_attributes(:title => "Test 3")
+end
+
+# globally disable all history tracking
+Mongoid::History.disable do
+  comment.update_attributes(:title => "Test 3")
+  user.update_attributes(:name => "Eddie Van Halen")
+end
+```
+
+**Retrieving the list of tracked fields**
+
+```ruby
+class Book
+  ...
+  field             :title
+  field             :author
+  field             :price
+  track_history     :on => [:title, :price]
+end
+
+Book.tracked_fields           #=> ["title", "price"]
+Book.tracked_field?(:title)   #=> true
+Book.tracked_field?(:author)  #=> false
+```
+
+**Displaying history trackers as an audit trail**
+
+In your Controller:
+
+```ruby
+# Fetch history trackers
+@trackers = HistoryTracker.limit(25)
+
+# get change set for the first tracker
+@changes = @trackers.first.tracked_changes
+  #=> {field: {to: val1, from: val2}}
+
+# get edit set for the first tracker
+@edits = @trackers.first.tracked_edits
+  #=> { add: {field: val},
+  #     remove: {field: val},
+  #     modify: { to: val1, from: val2 },
+  #     array: { add: [val2], remove: [val1] } }
+```
+
+In your View, you might do something like (example in HAML format):
+
+```haml
+%ul.changes
+  - (@edits[:add]||[]).each do |k,v|
+    %li.remove Added field #{k} value #{v}
+
+  - (@edits[:modify]||[]).each do |k,v|
+    %li.modify Changed field #{k} from #{v[:from]} to #{v[:to]}
+
+  - (@edits[:array]||[]).each do |k,v|
+    %li.modify
+      - if v[:remove].nil?
+        Changed field #{k} by adding #{v[:add]}
+      - elsif v[:add].nil?
+        Changed field #{k} by removing #{v[:remove]}
+      - else
+        Changed field #{k} by adding #{v[:add]} and removing #{v[:remove]}
+
+  - (@edits[:remove]||[]).each do |k,v|
+    %li.remove Removed field #{k} (was previously #{v})
+```
+
+**Adding Userstamp on History Trackers**
+
+To track the User in the application who created the HistoryTracker, please add the
+[Mongoid::Userstamp gem](https://github.com/tbpro/mongoid_userstamp) to your HistoryTracker class.
+This will add a field called `created_by` and an accessor `creator` to the model (you can rename these via gem config).
+
+```
+class MyHistoryTracker
+  include Mongoid::History::Tracker
+  include Mongoid::Userstamp
+end
+```
+
+*Migrating Userstamp from Previous Versions*
+
+Since October 2013 (mongoid-history version 0.4.1 and onwards), Mongoid::History itself no longer supports the userstamp natively. In order to migrate, follow the
+instructions above then run the following command:
+
+```
+MyHistoryTracker.all.each{|ht| ht.rename(:modifier_id, :created_by)
+```
+
+**Using an alternate changes method**
+
+Sometimes you may wish to provide an alternate method for determining which changes should be tracked.  For example, if you are using embedded documents
+and nested attributes, you may wish to write your own changes method that includes changes from the embedded documents.
+
+Mongoid::History provides an option named `:changes_method` which allows you to do this.  It defaults to `:changes`, which is the standard changes method.
+
+Example:
+
+```ruby
+class Foo
+  include Mongoid::Document
+  include Mongoid::Timestamps
+  include Mongoid::History::Trackable
+
+  field      :bar
+  embeds_one :baz
+  accepts_nested_attributes_for :baz
+
+  # use changes_with_baz to include baz's changes in this document's
+  # history.
+  track_history     :changes_method => :changes_with_baz
+
+  def changes_with_baz
+    if baz.changed?
+      changes.merge( :baz => summarized_changes(baz) )
+    else
+      changes
+    end
+  end
+
+  private
+  # This method takes the changes from an embedded doc and formats them
+  # in a summarized way, similar to how the embedded doc appears in the
+  # parent document's attributes
+  def summarized_changes obj
+    obj.changes.keys.map do |field|
+      next unless obj.respond_to?("#{field}_change")
+      [ { field => obj.send("#{field}_change")[0] },
+        { field => obj.send("#{field}_change")[1] } ]
+    end.compact.transpose.map do |fields|
+      fields.inject({}) {|map,f| map.merge(f)}
+    end
+  end
+end
+
+class Baz
+  include Mongoid::Document
+  include Mongoid::Timestamps
+
+  embedded_in :foo
+  field :value
+end
+```
+
+For more examples, check out [spec/integration/integration_spec.rb](https://github.com/aq1018/mongoid-history/blob/master/spec/integration/integration_spec.rb).
+
+Contributing to mongoid-history
+-------------------------------
+
+You're encouraged to contribute to this library. See [CONTRIBUTING](CONTRIBUTING.md) for details.
+
+Copyright
+---------
+
+Copyright (c) 2011-2012 Aaron Qian. MIT License.
+
+See [LICENSE.txt](https://github.com/aq1018/mongoid-history/blob/master/LICENSE.txt) for further details.
+
+
+
+[![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/aq1018/mongoid-history/trend.png)](https://bitdeli.com/free "Bitdeli Badge")