activerecord-userstamp 2.1.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aeb470b53728ed92b0b74621e4bd002a41d56275
-  data.tar.gz: c3c5f02aa4d41923407b92c17e99e6ceba1889a7
+  metadata.gz: 6113fc9e7a0eec6ad0ebe4f883c2b07d0f10d3f2
+  data.tar.gz: 481179a5004384a5f8173cd04efaf69f7bee1e37
 SHA512:
-  metadata.gz: fcd728fc959bb391efb41b47259541d385b1146039992f6a9860f34dc601fadef888258e3f080246a155aa40ad19bfb6452dc84fcf20632322e6fc8b5148f461
-  data.tar.gz: 43e02f3aea8be19d8a11148603b3cc6e875dce661ee3f55923594091140b3b928bc634773b81163c307dc1af772d77b56a86d57f361e0af38c5cd46d848e0f83
+  metadata.gz: 4a0260351476dde1e1893b9182bff0c19eb8118c9fa5d30db8b1be28a22dcdce1ea4a7a346e39bd0ff81a42e91a1a44b29e4c2f5d1ccacba485f12b0451f2d33
+  data.tar.gz: 8661e0637d5ee7231ac426243f9b1ceec0e03b42ac980d269462f243b054feaadb3717a7c3d2dc5eca5e0ae429bd436215d7c1d0f7c8237c0debf363a3711d1e

data/.gitignore

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

data/.rspec

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

data/CHANGELOG.md

@@ -0,0 +1,80 @@
+ # Changelog
+
+ ## 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,220 +1,188 @@
-# 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.
-
-## 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.
-
-### 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'
-```
-
-Ensure that each model has a set of columns for creators, updaters, and deleters (if applicable.)
-
-```ruby
-  class CreateUsers < ActiveRecord::Migration
-    def self.up
-      create_table :users, :force => true do |t|
-        ...
-        t.userstamps # use t.userstamps(true) if you also want 'deleter_id'
-      end
-    end
-
-    def self.down
-      drop_table :users
-    end
-  end
-
-  class CreatePosts < ActiveRecord::Migration
-    def self.up
-      create_table :posts, :force => true do |t|
-        ...
-        t.userstamps # use t.userstamps(true) if you also want 'deleter_id'
-      end
-    end
-
-    def self.down
-      drop_table :posts
-    end
-  end
-```
-
-Declare the stamper on the User model:
-
-```ruby
-  class User < ActiveRecord::Base
-    model_stamper
-  end
-```
-
-And declare that the Posts are stampable:
-
-```ruby
-  class Post < ActiveRecord::Base
-    stampable
-  end
-```
-
-If your stamper is called `User`, that's it; you're done.
-
-## Customisation
-More than likely you want all your associations setup on your stamped objects, and that's where the
-`stampable` class method comes in. So in our example we'll want to use this method in both our 
-User and Post classes:
-
-```ruby
-  class User < ActiveRecord::Base
-    model_stamper
-    stampable
-  end
-
-  class Post < ActiveRecord::Base
-    stampable
-  end
-```
-
-Okay, so what all have we done? The `model_stamper` class method injects two methods into the
-`User` class. They are `#stamper=` and `#stamper` and look like this:
-
-  def stamper=(object)
-    object_stamper = if object.is_a?(ActiveRecord::Base)
-      object.send("#{object.class.primary_key}".to_sym)
-    else
-      object
-    end
-
-    Thread.current["#{self.to_s.downcase}_#{self.object_id}_stamper"] = object_stamper
-  end
-
-  def stamper
-    Thread.current["#{self.to_s.downcase}_#{self.object_id}_stamper"]
-  end
-
-The `stampable` method allows you to customize what columns will get stamped, and also creates the
-`creator`, `updater`, and `deleter` associations.
-
-The Userstamp module that we included into our ApplicationController uses the setter method to
-set which user is currently making the request. By default the 'set_stampers' method works perfectly
-with the RestfulAuthentication[http://svn.techno-weenie.net/projects/plugins/restful_authentication] plug-in:
-
-  def set_stampers
-    User.stamper = self.current_user
-  end
-
-If you aren't using ActsAsAuthenticated, then you need to create your own version of the
-<tt>set_stampers</tt> method in the controller where you've included the Userstamp module.
-
-Now, let's get back to the Stampable module (since it really is the interesting one). The Stampable
-module sets up before_* filters that are responsible for setting those attributes at the appropriate
-times. It also creates the belongs_to relationships for you.
-
-If you need to customize the columns that are stamped, the <tt>stampable</tt> method can be
-completely customized. Here's an quick example:
-
-  class Post < ActiveRecord::Base
-    stampable :stamper_class_name => :person,
-              :creator_attribute  => :create_user,
-              :updater_attribute  => :update_user,
-              :deleter_attribute  => :delete_user,
-              :deleter => true,
-              :with_deleted => true
-  end
-
-## 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.
-
-Furthermore, there is no need to include the `Userstamp` module in `ApplicationController`.
-
-However, this is where the bulk of the work is: since this is a fork of insphire's gem, where he 
-has removed making every `ActiveRecord::Base` subclass automatically a 
-
-### Upgrading from magiclabs-userstamp
-
-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.
+
+## 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.
+
+### 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)