activerecord-userstamp 3.0.2 → 3.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 56c177f02be82c8c7a1a66cf7b7392d862b25efa
-  data.tar.gz: 7f8d80e37b76903dcc04125b62657355d96e0619
+  metadata.gz: 352c22aa4ca4d1dd7c9cc5ff0a7c3e9e2ccf9ba1
+  data.tar.gz: bf2df186ca39cb6ff78370ac3eca3e9e13624b64
 SHA512:
-  metadata.gz: ff83831f18094fc7fd05d4f8396b38eae47e1b3d45a180f9909964d6d333fdd660ca420df7d79c0df1cc45c3df7ecf0b500844b84ae0d83d5ad4bfe27429a4e0
-  data.tar.gz: 1b5a4812a59624987bd4a9201b5845ed3a23f7af40c1b7b01bf749dffc2410047e50a841d39786a40d0b50b12412d90417791cc7926ee5874b155d86cd745660
+  metadata.gz: cb311b3579621119fa951df7a229e67bd3593bccf3a025e0e47ca1d6fd34b906e2dad3bf74474a7beb66929940a2ad463d928776c11f9256816c40b42a5d8d7e
+  data.tar.gz: 4e7114880578dd234f11b25ed44c8773b44480037672b8895a8586bbfdb78c1dc269c6175c0296c3abe07bd080c57775434da4f89b41d14ad68ab38cd529479f

data/.gitignore

@@ -1,5 +1,5 @@
-*.log
-*.sqlite3
-/.rdoc
-/spec/examples.txt
-/.bundle
+*.log
+*.sqlite3
+/.rdoc
+/.bundle
+/spec/examples.txt

data/.rspec

@@ -1,2 +1,2 @@
---color
---require spec_helper
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -1,99 +1,103 @@
- # Changelog
- ## 3.0.2 (12-7-2015)
-  * Joel Low          - Depending on what was set to a stamper (ID or record object), the
-                        association ID or association setter is used to assign the
-                        creator/updater/deleter attributes. This only applies if the attributes
-                        end with `_id`; otherwise the attribute would be used verbatim (e.g. the
-                        compatibility mode `created_by`).
-  * Joel Low          - Provide a `with_stamper` method to specify the stamper for a given
-                        stamper class during the execution of the block.
-  * Joel Low          - Ensure that the `set_stamper` and `reset_stamper` calls from the
-                        controller are always paired so that the stamper state is always properly
-                        restored. `set_stamper` and `reset_stamper` is now deprecated and will be
-                        removed in ActiveRecord::Userstamp 3.1 and replaced with a single
-                        `with_stamper` `around_action` callback.
-
- ## 3.0.1 (11-7-2015)
-  * Joel Low          - Only declare the creator/updater/deleter associations when the table has
-                        the attribute columns. If the columns cannot be determined (e.g. if the
-                        table has not been defined, such as during tests), then the model would
-                        need to explicitly call `stampable`.
-
- ## 3.0.0 (10-7-2015)
-  * Joel Low          - Remove `compatibility_mode`. Use the `creator_attribute`,
-                        `updater_attribute`, and `deleter_attribute` configuration options instead.
-  * Joel Low          - The table definition migration helper should follow the gem configuration
-                        when generating column names.
-  * Joel Low          - When deciding whether to generate a `deleter_id` column, check the gem
-                        configuration for the `deleter_attribute` configuration option instead of
-                        relying on the user to specify in every migration.
-  * Joel Low          - Remove the `deleter` option from the `stampable` model declaration.
-  * Joel Low          - Remove the `creator_attribute`, `updater_attribute`, and `deleter_attribute`
-                        options from the `stampable` model declaration. All models will follow
-                        the gem configuration.
-  * Joel Low          - Added the `default_stamper` configuration option. The controller will
-                        automatically stamp using that model.
-  * Joel Low          - Additional attributes passed to `stampable` would be passed to the
-                        underlying `belongs_to` association.
-  * Joel Low          - Declare the creator/updater/deleter setter callbacks directly in
-                        `ActiveRecord::Base`. So now, all models will automatically be stamped
-                        when the creator/updater/deleter attributes are present. This mirrors
-                        `ActiveRecord::Timestamp` behaviour.
-  * Joel Low          - Automatically declare the creator/updater/deleter associations on every
-                        model. To add additional configuration options, simply call `stampable`.
-                        This can be called multiple times per model; the last call takes effect.
-  * Joel Low          - Remove support for `serialized_attributes`. It will be removed in Rails 5.
-
- ## 2.1.1 (9-7-2015)
-
-  * Chris Hilton      - Only set updater attribute if the record has changed or contains a
-                        serialized attribute.
-  * Chris Hilton      - Support `:with_deleted` in the `stampable` declaration.
-  * Chris Hilton      - Only set the creator attribute if it is blank.
-  * Chris Branson     - Fix deprecation warning in `serialized_attributes`.
-  * Joel Low          - Trigger the updater/creator stamping before saving, so that the correct
-                        users are stamped even if validation was not run.
-  * Joel Low          - Allow extra parameters to be passed to the migration helpers.
-
-## 2.1.0 (28-3-2014)
-  * Thomas von Deyen  - Do not automatically make every class stampable.
-
-## 2.0.2 (11-8-2011)
-  * Chris Hilton      - Set the creator/updater attributes before validation, so that they can
-                        be checked as part of validations.
-  * Alex              - Specify that the stampable class is camelized from the given symbol,
-                        not just capitalized, to follow ActiveRecord convention.
-## 2.0.1 (8-10-2010)
-  * Michael Grosser   -  Make stampable define the deleter association and before filter whenever
-                         a :deleter_attribute has been passed in options, or :deleter => true is
-                         passed, or Caboose::Acts::Paranoid is defined. This makes :deleter
-                         functionality useable to people who aren't use acts_as_paranoid.
-  * Michael Grosser   -  do not leave record_userstamp turned on when an exception occurs inside
-                         the `without_stamps` block
-
-## 2.0 (2-17-2008)
-  * Ben Wyrosdick    - Added a migration helper that gives migration scripts a <tt>userstamps</tt>
-                       method.
-  * Marshall Roch    - Stamping can be temporarily turned off using the 'without_stamps' class
-                       method.
-    Example:
-      Post.without_stamps do
-        post = Post.find(params[:id])
-        post.update_attributes(params[:post])
-        post.save
-      end
-
-  * Models that should receive updates made by 'stampers' now use the acts_as_stampable class
-    method. This sets up the belongs_to relationships and also injects private methods for use by
-    the individual callback filter methods.
-
-  * Models that are responsible for updating now use the acts_as_stamper class method. This
-    injects the stamper= and stamper methods that are thread safe and should be updated per
-    request by a controller.
-
-  * The Userstamp module is now meant to be included with one of your project's controllers (the
-    Application Controller is recommended). It creates a before filter called 'set_stampers' that
-    is responsible for setting all the current Stampers.
-
-## 1.0 (01-18-2006)
-  * Initial Release
+ # Changelog
+ ## 3.0.3 (14-7-2015)
+  * Joel Low          - Allow using ActiveRecord-Userstamp with generated tables (e.g. 
+                        `has_and_belongs_to_many` join tables.)
+
+ ## 3.0.2 (12-7-2015)
+  * Joel Low          - Depending on what was set to a stamper (ID or record object), the
+                        association ID or association setter is used to assign the
+                        creator/updater/deleter attributes. This only applies if the attributes
+                        end with `_id`; otherwise the attribute would be used verbatim (e.g. the
+                        compatibility mode `created_by`).
+  * Joel Low          - Provide a `with_stamper` method to specify the stamper for a given
+                        stamper class during the execution of the block.
+  * Joel Low          - Ensure that the `set_stamper` and `reset_stamper` calls from the
+                        controller are always paired so that the stamper state is always properly
+                        restored. `set_stamper` and `reset_stamper` is now deprecated and will be
+                        removed in ActiveRecord::Userstamp 3.1 and replaced with a single
+                        `with_stamper` `around_action` callback.
+
+ ## 3.0.1 (11-7-2015)
+  * Joel Low          - Only declare the creator/updater/deleter associations when the table has
+                        the attribute columns. If the columns cannot be determined (e.g. if the
+                        table has not been defined, such as during tests), then the model would
+                        need to explicitly call `stampable`.
+
+ ## 3.0.0 (10-7-2015)
+  * Joel Low          - Remove `compatibility_mode`. Use the `creator_attribute`,
+                        `updater_attribute`, and `deleter_attribute` configuration options instead.
+  * Joel Low          - The table definition migration helper should follow the gem configuration
+                        when generating column names.
+  * Joel Low          - When deciding whether to generate a `deleter_id` column, check the gem
+                        configuration for the `deleter_attribute` configuration option instead of
+                        relying on the user to specify in every migration.
+  * Joel Low          - Remove the `deleter` option from the `stampable` model declaration.
+  * Joel Low          - Remove the `creator_attribute`, `updater_attribute`, and `deleter_attribute`
+                        options from the `stampable` model declaration. All models will follow
+                        the gem configuration.
+  * Joel Low          - Added the `default_stamper` configuration option. The controller will
+                        automatically stamp using that model.
+  * Joel Low          - Additional attributes passed to `stampable` would be passed to the
+                        underlying `belongs_to` association.
+  * Joel Low          - Declare the creator/updater/deleter setter callbacks directly in
+                        `ActiveRecord::Base`. So now, all models will automatically be stamped
+                        when the creator/updater/deleter attributes are present. This mirrors
+                        `ActiveRecord::Timestamp` behaviour.
+  * Joel Low          - Automatically declare the creator/updater/deleter associations on every
+                        model. To add additional configuration options, simply call `stampable`.
+                        This can be called multiple times per model; the last call takes effect.
+  * Joel Low          - Remove support for `serialized_attributes`. It will be removed in Rails 5.
+
+ ## 2.1.1 (9-7-2015)
+
+  * Chris Hilton      - Only set updater attribute if the record has changed or contains a
+                        serialized attribute.
+  * Chris Hilton      - Support `:with_deleted` in the `stampable` declaration.
+  * Chris Hilton      - Only set the creator attribute if it is blank.
+  * Chris Branson     - Fix deprecation warning in `serialized_attributes`.
+  * Joel Low          - Trigger the updater/creator stamping before saving, so that the correct
+                        users are stamped even if validation was not run.
+  * Joel Low          - Allow extra parameters to be passed to the migration helpers.
+
+## 2.1.0 (28-3-2014)
+  * Thomas von Deyen  - Do not automatically make every class stampable.
+
+## 2.0.2 (11-8-2011)
+  * Chris Hilton      - Set the creator/updater attributes before validation, so that they can
+                        be checked as part of validations.
+  * Alex              - Specify that the stampable class is camelized from the given symbol,
+                        not just capitalized, to follow ActiveRecord convention.
+## 2.0.1 (8-10-2010)
+  * Michael Grosser   -  Make stampable define the deleter association and before filter whenever
+                         a :deleter_attribute has been passed in options, or :deleter => true is
+                         passed, or Caboose::Acts::Paranoid is defined. This makes :deleter
+                         functionality useable to people who aren't use acts_as_paranoid.
+  * Michael Grosser   -  do not leave record_userstamp turned on when an exception occurs inside
+                         the `without_stamps` block
+
+## 2.0 (2-17-2008)
+  * Ben Wyrosdick    - Added a migration helper that gives migration scripts a <tt>userstamps</tt>
+                       method.
+  * Marshall Roch    - Stamping can be temporarily turned off using the 'without_stamps' class
+                       method.
+    Example:
+      Post.without_stamps do
+        post = Post.find(params[:id])
+        post.update_attributes(params[:post])
+        post.save
+      end
+
+  * Models that should receive updates made by 'stampers' now use the acts_as_stampable class
+    method. This sets up the belongs_to relationships and also injects private methods for use by
+    the individual callback filter methods.
+
+  * Models that are responsible for updating now use the acts_as_stamper class method. This
+    injects the stamper= and stamper methods that are thread safe and should be updated per
+    request by a controller.
+
+  * The Userstamp module is now meant to be included with one of your project's controllers (the
+    Application Controller is recommended). It creates a before filter called 'set_stampers' that
+    is responsible for setting all the current Stampers.
+
+## 1.0 (01-18-2006)
+  * Initial Release

data/Gemfile

@@ -1,3 +1,3 @@
-source 'https://rubygems.org'
-
-gemspec
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -1,21 +1,21 @@
-Copyright (c) 2006-2008 DeLynn Berry
-Copyright (c) 2014-2015 Joel Low
-
-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) 2006-2008 DeLynn Berry
+Copyright (c) 2014-2015 Joel Low
+
+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,189 +1,189 @@
-# ActiveRecord-Userstamp [![Build Status](https://travis-ci.org/lowjoel/activerecord-userstamp.svg)](https://travis-ci.org/lowjoel/activerecord-userstamp) [![Coverage Status](https://coveralls.io/repos/lowjoel/activerecord-userstamp/badge.svg?branch=master&service=github)](https://coveralls.io/github/lowjoel/activerecord-userstamp?branch=master) [![Code Climate](https://codeclimate.com/github/lowjoel/activerecord-userstamp/badges/gpa.svg)](https://codeclimate.com/github/lowjoel/activerecord-userstamp)
-
-## Overview
-
-Userstamp extends `ActiveRecord::Base` to add automatic updating of `creator`, `updater`, and 
-`deleter` attributes. It is based loosely on `ActiveRecord::Timestamp`.
-
-Two class methods (`model_stamper` and `stampable`) are implemented in this gem. The `model_stamper`
-method is used in models that are responsible for creating, updating, or deleting other objects.
-Typically this would be the `User` model of your application. The `stampable` method is used in 
-models that are subject to being created, updated, or deleted by stampers.
-
-## Forkception
-
-This is a fork of:
-
- - the [magiclabs-userstamp](https://github.com/magiclabs/userstamp) gem
- - which is a fork of [Michael Grosser's](https://github.com/grosser)
-   [userstamp gem] (https://github.com/grosser/userstamp) 
- - which is a fork of the original [userstamp plugin](https://github.com/delynn/userstamp) by
-   [delynn](https://github.com/delynn)
-
-In addition to these, I have cherry picked ideas and changes from the following forks:
-
- - [simplificator](https://github.com/simplificator/userstamp)
- - [akm](https://github.com/akm/magic_userstamp)
- - [konvenit](https://github.com/konvenit/userstamp)
-
-Finally, this gem only supports Ruby 2.0 and above. Yes, you really should upgrade to a supported
-version of Ruby. This gem is tested only on Rails 4.2; but it should work with Rails 4+.
-
-## Features
-### Soft-deletes
-The reason for this is because the original userstamp plugin does not support databases utilising
-soft deletes. They are not tested explicitly within this gem, but it is expected to work with the
-following gems:
-
- - [acts_as_paranoid](https://github.com/ActsAsParanoid/acts_as_paranoid)
- - [paranoia](https://github.com/radar/paranoia)
-
-The `stampable` method has been modified to allow additional arguments to be passed to the 
-creator/updater relations. This allows declarations like:
-
-```ruby
-  stampable with_deleted: true
-```
-
-to result in a `belongs_to` relation which looks like:
-
-```ruby
-  belongs_to :creator, class_name: '::User', foreign_key: :created_by, with_deleted: true
-```
-
-Do create a ticket if it is broken, with a pull-request if possible.  
-
-### Customisable column names/types
-While examining the userstamp gem's network on Github, it was noticed that quite a few forks were
-made to allow customisability in the name and type of the column with the database migration.
-
-This gem now supports customised column names. See the [usage](#usage) section on the
-configuration options supported.
-
-### Saving before validation
-This fork includes changes to perform model stamping before validation. This allows models to
-enforce the presence of stamp attributes:
-
-```ruby
-  validates :created_by, presence: true
-  validates :updated_by, presence: true
-```
-
-Furthermore, the `creator` attribute is set only if the value is blank allowing for a manual
-override.
-
-## Usage
-Assume that we are building a blog application, with User and Post objects. Add the following 
-to the application's Gemfile:
-
-```ruby
-  gem 'activerecord-userstamp'
-```
-
-Define an initializer in your Rails application to configure the gem:
-
-```ruby
-ActiveRecord::Userstamp.configure do |config|
-  # config.default_stamper = 'User'
-  # config.creator_attribute = :creator_id
-  # config.updater_attribute = :updater_id
-  config.deleter_attribute = nil
-end
-```
-
-By default, `:deleter_attribute` is set to `:deleter_id` for soft deletes. If you are not using
-soft deletes, you can set the attribute no `nil`.
-
-Ensure that each model has a set of columns for creators, updaters, and deleters (if applicable.)
-
-```ruby
-  class CreateUsers < ActiveRecord::Migration
-    def change
-      create_table :users do |t|
-        ...
-        t.userstamps
-      end
-    end
-  end
-
-  class CreatePosts < ActiveRecord::Migration
-    def change
-      create_table :posts do |t|
-        ...
-        t.userstamps
-      end
-    end
-  end
-```
-
-Declare the stamper on the User model:
-
-```ruby
-  class User < ActiveRecord::Base
-    model_stamper
-  end
-```
-
-If your stamper is called `User`, that's it; you're done.
-
-## Customisation
-The association which is created on each of the `creator_id`, `updater_id`, and `deleter_id` can
-be customised. Also, the stamper used by each class can also be customised. For this purpose, the
- `ActiveRecord::Base.stampable` method can be used:
-
-```ruby
-  class Post < ActiveRecord::Base
-    stampable
-  end
-```
-
-The `stampable` method allows you to customize the `creator`, `updater`, and `deleter` associations.
-It also allows you to specify the name of the stamper for the class being declared. Any additional
-arguments are passed to the `belongs_to` declaration.
-
-## Upgrading
-### Upgrading from delynn's 1.x/2.x with `compatibility_mode`
-The major difference between 1.x and 2.x is the naming of the columns. This version of the gem 
-allows specifying the name of the column from the gem configuration:
-
-```ruby
-ActiveRecord::Userstamp.configure do |config|
-  config.creator_attribute = :created_by
-  config.updater_attribute = :updated_by
-  config.deleter_attribute = :deleted_by
-end
-```
-
-### Upgrading from delynn's 2.x without `compatibility_mode`
-Within migrations, it was possible to declare `t.userstamps` within a table definition. It used
-to accept one argument, which declares whether the deleter column should be created. This has
-been changed to respect the gem configuration's `deleter_attribute`. If that is `nil`, then no
-deleter column would be created.
-
-There is also no need to include the `Userstamp` module in `ApplicationController`.
-
-### Upgrading from insphire's 2.0.1, or magiclabs-userstamp 2.0.2 or 2.1.0
-
-That version of the gem allows every model to declare the name of the column containing the
-attribute. That also means that in a large project, every model needs to declare `stampable`,
-which is not very DRY.
-
-To use this gem, normalise all database columns to use a consistent set of column names.
-Configure the gem to use those names (as above) and remove all `stampable` declarations.
-
-There is no need to include the `Userstamp` module in `ApplicationController`.
-
-## Tests
-Run
-
-    $ bundle exec rspec
-
-## Authors
- - [DeLynn Berry](http://delynnberry.com/): The original idea for this plugin came from the Rails
-   Wiki article entitled
-   [Extending ActiveRecord](http://wiki.rubyonrails.com/rails/pages/ExtendingActiveRecordExample)
- - [Michael Grosser](http://pragmatig.com)
- - [John Dell](http://blog.spovich.com/)
- - [Chris Hilton](https://github.com/chrismhilton)
- - [Thomas von Deyen](https://github.com/tvdeyen)
- - [Joel Low](http://joelsplace.sg)
+# ActiveRecord-Userstamp [![Build Status](https://travis-ci.org/lowjoel/activerecord-userstamp.svg)](https://travis-ci.org/lowjoel/activerecord-userstamp) [![Coverage Status](https://coveralls.io/repos/lowjoel/activerecord-userstamp/badge.svg?branch=master&service=github)](https://coveralls.io/github/lowjoel/activerecord-userstamp?branch=master) [![Code Climate](https://codeclimate.com/github/lowjoel/activerecord-userstamp/badges/gpa.svg)](https://codeclimate.com/github/lowjoel/activerecord-userstamp)
+
+## Overview
+
+Userstamp extends `ActiveRecord::Base` to add automatic updating of `creator`, `updater`, and 
+`deleter` attributes. It is based loosely on `ActiveRecord::Timestamp`.
+
+Two class methods (`model_stamper` and `stampable`) are implemented in this gem. The `model_stamper`
+method is used in models that are responsible for creating, updating, or deleting other objects.
+Typically this would be the `User` model of your application. The `stampable` method is used in 
+models that are subject to being created, updated, or deleted by stampers.
+
+## Forkception
+
+This is a fork of:
+
+ - the [magiclabs-userstamp](https://github.com/magiclabs/userstamp) gem
+ - which is a fork of [Michael Grosser's](https://github.com/grosser)
+   [userstamp gem] (https://github.com/grosser/userstamp) 
+ - which is a fork of the original [userstamp plugin](https://github.com/delynn/userstamp) by
+   [delynn](https://github.com/delynn)
+
+In addition to these, I have cherry picked ideas and changes from the following forks:
+
+ - [simplificator](https://github.com/simplificator/userstamp)
+ - [akm](https://github.com/akm/magic_userstamp)
+ - [konvenit](https://github.com/konvenit/userstamp)
+
+Finally, this gem only supports Ruby 2.0 and above. Yes, you really should upgrade to a supported
+version of Ruby. This gem is tested only on Rails 4.2; but it should work with Rails 4+.
+
+## Features
+### Soft-deletes
+The reason for this is because the original userstamp plugin does not support databases utilising
+soft deletes. They are not tested explicitly within this gem, but it is expected to work with the
+following gems:
+
+ - [acts_as_paranoid](https://github.com/ActsAsParanoid/acts_as_paranoid)
+ - [paranoia](https://github.com/radar/paranoia)
+
+The `stampable` method has been modified to allow additional arguments to be passed to the 
+creator/updater relations. This allows declarations like:
+
+```ruby
+  stampable with_deleted: true
+```
+
+to result in a `belongs_to` relation which looks like:
+
+```ruby
+  belongs_to :creator, class_name: '::User', foreign_key: :created_by, with_deleted: true
+```
+
+Do create a ticket if it is broken, with a pull-request if possible.  
+
+### Customisable column names/types
+While examining the userstamp gem's network on Github, it was noticed that quite a few forks were
+made to allow customisability in the name and type of the column with the database migration.
+
+This gem now supports customised column names. See the [usage](#usage) section on the
+configuration options supported.
+
+### Saving before validation
+This fork includes changes to perform model stamping before validation. This allows models to
+enforce the presence of stamp attributes:
+
+```ruby
+  validates :created_by, presence: true
+  validates :updated_by, presence: true
+```
+
+Furthermore, the `creator` attribute is set only if the value is blank allowing for a manual
+override.
+
+## Usage
+Assume that we are building a blog application, with User and Post objects. Add the following 
+to the application's Gemfile:
+
+```ruby
+  gem 'activerecord-userstamp'
+```
+
+Define an initializer in your Rails application to configure the gem:
+
+```ruby
+ActiveRecord::Userstamp.configure do |config|
+  # config.default_stamper = 'User'
+  # config.creator_attribute = :creator_id
+  # config.updater_attribute = :updater_id
+  config.deleter_attribute = nil
+end
+```
+
+By default, `:deleter_attribute` is set to `:deleter_id` for soft deletes. If you are not using
+soft deletes, you can set the attribute no `nil`.
+
+Ensure that each model has a set of columns for creators, updaters, and deleters (if applicable.)
+
+```ruby
+  class CreateUsers < ActiveRecord::Migration
+    def change
+      create_table :users do |t|
+        ...
+        t.userstamps
+      end
+    end
+  end
+
+  class CreatePosts < ActiveRecord::Migration
+    def change
+      create_table :posts do |t|
+        ...
+        t.userstamps
+      end
+    end
+  end
+```
+
+Declare the stamper on the User model:
+
+```ruby
+  class User < ActiveRecord::Base
+    model_stamper
+  end
+```
+
+If your stamper is called `User`, that's it; you're done.
+
+## Customisation
+The association which is created on each of the `creator_id`, `updater_id`, and `deleter_id` can
+be customised. Also, the stamper used by each class can also be customised. For this purpose, the
+ `ActiveRecord::Base.stampable` method can be used:
+
+```ruby
+  class Post < ActiveRecord::Base
+    stampable
+  end
+```
+
+The `stampable` method allows you to customize the `creator`, `updater`, and `deleter` associations.
+It also allows you to specify the name of the stamper for the class being declared. Any additional
+arguments are passed to the `belongs_to` declaration.
+
+## Upgrading
+### Upgrading from delynn's 1.x/2.x with `compatibility_mode`
+The major difference between 1.x and 2.x is the naming of the columns. This version of the gem 
+allows specifying the name of the column from the gem configuration:
+
+```ruby
+ActiveRecord::Userstamp.configure do |config|
+  config.creator_attribute = :created_by
+  config.updater_attribute = :updated_by
+  config.deleter_attribute = :deleted_by
+end
+```
+
+### Upgrading from delynn's 2.x without `compatibility_mode`
+Within migrations, it was possible to declare `t.userstamps` within a table definition. It used
+to accept one argument, which declares whether the deleter column should be created. This has
+been changed to respect the gem configuration's `deleter_attribute`. If that is `nil`, then no
+deleter column would be created.
+
+There is also no need to include the `Userstamp` module in `ApplicationController`.
+
+### Upgrading from insphire's 2.0.1, or magiclabs-userstamp 2.0.2 or 2.1.0
+
+That version of the gem allows every model to declare the name of the column containing the
+attribute. That also means that in a large project, every model needs to declare `stampable`,
+which is not very DRY.
+
+To use this gem, normalise all database columns to use a consistent set of column names.
+Configure the gem to use those names (as above) and remove all `stampable` declarations.
+
+There is no need to include the `Userstamp` module in `ApplicationController`.
+
+## Tests
+Run
+
+    $ bundle exec rspec
+
+## Authors
+ - [DeLynn Berry](http://delynnberry.com/): The original idea for this plugin came from the Rails
+   Wiki article entitled
+   [Extending ActiveRecord](http://wiki.rubyonrails.com/rails/pages/ExtendingActiveRecordExample)
+ - [Michael Grosser](http://pragmatig.com)
+ - [John Dell](http://blog.spovich.com/)
+ - [Chris Hilton](https://github.com/chrismhilton)
+ - [Thomas von Deyen](https://github.com/tvdeyen)
+ - [Joel Low](http://joelsplace.sg)