paper_trail 4.0.0 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e6cf60ba027274553881419d2024a86547be00d2
-  data.tar.gz: 57495d17ebfa11d24a17cf7d65ba5e67aca92816
+  metadata.gz: 047fe27b3f2154c19030502f4d129dcdd2873146
+  data.tar.gz: 6b6f268b260b459e0e6df8340ec9d33cb5c07824
 SHA512:
-  metadata.gz: d9c462e7bb9dfdf1404de3fb8de7484de342ab0516e0e8eaae67e3059a51e01d0e7c9b1699433857c2045bee768256ab811783ccc8568318cf14dc39c50bd6ff
-  data.tar.gz: 1e8c8098fa91e2cb9af8fae20268beceba18e885948a629e5fada7d84d2023159254da16875341436ce620365fb9f28432e4a37159ac7a9c8bc8883a2afef409
+  metadata.gz: 49c10975deb4b0f20617b4b770a1f6b99d2980df4072dd71da1dc48c7da85e409c6eeadcbfcc74f86f239b320e7ae73f6d7d2f72971439a39330d6f353b9f33e
+  data.tar.gz: 3ecddc1755c7d139e04716582bbe136163605eb33354acaf7e520bc0178dfe7c9d184c8f673f4bb744440c4e7113a58017c6de4fca9262ff99575bee764d804d

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 4.0.1
+
+### Breaking Changes
+
+- None
+
+### Added
+
+- None
+
+### Fixed
+
+- [#636](https://github.com/airblade/paper_trail/issues/636) -
+  Should compile assets without a db connection
+- [#589](https://github.com/airblade/paper_trail/pull/589) /
+  [#588](https://github.com/airblade/paper_trail/issues/588) -
+  Fixes timestamp for "create" versions
+
 ## 4.0.0
 
 This major release adds JSON column support in PostgreSQL, limited support for
@@ -5,7 +23,7 @@ versioning associations, various new configuration options, and a year's worth
 of bug fixes. Thanks to everyone who helped test the two betas and two release
 candidates.
 
-### Changed
+### Breaking Changes
 
 - Using a Rails initializer to reopen PaperTrail::Version or otherwise extend
   PaperTrail is no longer recommended. An alternative is described in the
@@ -13,6 +31,9 @@ candidates.
   https://github.com/airblade/paper_trail/pull/492.
 - If you depend on the `RSpec` or `Cucumber` helpers, you must
   [require them in your test helper](https://github.com/airblade/paper_trail#testing).
+- [#566](https://github.com/airblade/paper_trail/pull/566) - Removed deprecated
+  methods `paper_trail_on` and `paper_trail_off`. Use `paper_trail_on!` and
+  `paper_trail_off!` instead.
 - [#458](https://github.com/airblade/paper_trail/pull/458) - Version metadata
   (the `:meta` option) from AR attributes for `create` events will now save the
   current value instead of `nil`.
@@ -29,12 +50,6 @@ candidates.
 - `3da1f104` - `PaperTrail.config` and `PaperTrail.configure` are now
   identical: both return the `PaperTrail::Config` instance and also
   yield it if a block is provided.
-  
-### Removed
-
-- [#566](https://github.com/airblade/paper_trail/pull/566) - Removed deprecated
-  methods `paper_trail_on` and `paper_trail_off`. Use `paper_trail_on!` and
-  `paper_trail_off!` instead.
 
 ### Added
 

data/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+Thanks for your interest in PaperTrail! We appreciate bug reports, feature
+suggestions, and especially pull requests.
+
+Please do not use github issues to ask usage questions. We simply don't have
+time to answer them all. Instead, please ask usage questions on Stack Overflow.
+
+http://stackoverflow.com/tags/papertrail
+
+Thanks, and happy versioning :)

data/README.md

@@ -1,72 +1,76 @@
-# PaperTrail [![Build Status][4]][5] [![Dependency Status][6]][7]
+# PaperTrail
 
-PaperTrail lets you track changes to your models' data.  It's good for auditing
-or versioning.  You can see how a model looked at any stage in its lifecycle,
-revert it to any version, and even undelete it after it's been destroyed.
+[![Build Status][4]][5] [![Dependency Status][6]][7]
+
+Track changes to your models, for auditing or versioning. See how a model looked
+at any stage in its lifecycle, revert it to any version, or restore it after it
+has been destroyed.
 
 - [Features](#features)
 - [Compatibility](#compatibility)
 - [Installation](#installation)
 - [API Summary](#api-summary)
 - [Basic Usage](#basic-usage)
-- [Choosing Lifecycle Events To Monitor](#choosing-lifecycle-events-to-monitor)
-- [Choosing When To Save New Versions](#choosing-when-to-save-new-versions)
-- [Choosing Attributes To Monitor](#choosing-attributes-to-monitor)
-- [Reverting And Undeleting A Model](#reverting-and-undeleting-a-model)
-- [Navigating Versions](#navigating-versions)
+- Limiting What is Versioned, and When
+  - [Choosing Lifecycle Events To Monitor](#choosing-lifecycle-events-to-monitor)
+  - [Choosing When To Save New Versions](#choosing-when-to-save-new-versions)
+  - [Choosing Attributes To Monitor](#choosing-attributes-to-monitor)
+  - [Turning PaperTrail Off/On](#turning-papertrail-offon)
+  - [Limiting the Number of Versions Created](#limiting-the-number-of-versions-created)
+- Working With Versions
+  - [Reverting And Undeleting A Model](#reverting-and-undeleting-a-model)
+  - [Navigating Versions](#navigating-versions)
+  - [Diffing Versions](#diffing-versions)
+  - [Deleting Old Versions](#deleting-old-versions)
 - [Finding Out Who Was Responsible For A Change](#finding-out-who-was-responsible-for-a-change)
 - [Custom Version Classes](#custom-version-classes)
 - [Associations](#associations)
 - [Storing metadata](#storing-metadata)
-- [Diffing Versions](#diffing-versions)
-- [Turning PaperTrail Off/On](#turning-papertrail-offon)
 - [Using a custom serializer](#using-a-custom-serializer)
 - [SerializedAttributes support](#serializedattributes-support)
-- [Limiting the Number of Versions Created](#limiting-the-number-of-versions-created)
-- [Deleting Old Versions](#deleting-old-versions)
 - [Testing](#testing)
 
 ## Features
 
-* Stores every create, update and destroy (or only the lifecycle events you specify).
-* Does not store updates which don't change anything.
-* Allows you to specify attributes (by inclusion or exclusion) which must change for a Version to be stored.
-* Allows you to get at every version, including the original, even once destroyed.
-* Allows you to get at every version even if the schema has since changed.
-* Allows you to get at the version as of a particular time.
-* Option to automatically restore `has_one`, `has_many` and `has_many :through` associations as they were at the time.
-* Automatically records who was responsible via your controller.  PaperTrail calls `current_user` by default, if it exists, but you can have it call any method you like.
-* Allows you to set who is responsible at model-level (useful for migrations).
-* Allows you to store arbitrary model-level metadata with each version (useful for filtering versions).
-* Allows you to store arbitrary controller-level information with each version, e.g. remote IP.
-* Can be turned off/on per class (useful for migrations).
-* Can be turned off/on per request (useful for testing with an external service).
-* Can be turned off/on globally (useful for testing).
-* No configuration necessary.
-* Stores everything in a single database table by default (generates migration for you), or can use separate tables for separate models.
-* Supports custom version classes so different models' versions can have different behaviour.
-* Supports custom name for versions association.
-* Thoroughly tested.
-* Threadsafe.
-
+* Stores create, update and destroy events
+  * Does not store updates which don't change anything
+  * Support for versioning associated records
+* Can store metadata with each version record
+  * Who was responsible for a change
+  * Arbitrary model-level metadata (useful for filtering versions)
+  * Arbitrary controller-level information e.g. remote IP
+* Configurable
+  * No configuration necessary, but if you want to ..
+  * Configure which events (create, update and destroy) are versioned
+  * Configure which attributes must change for an update to be versioned
+  * Turn off/on by model, request, or globally
+  * Use separate tables for separate models
+* Extensible
+  * Write a custom version class for complete control
+  * Write custom version classes for each of your models
+* Work with versions
+  * Restore any version, including the original, even once destroyed
+  * Restore any version even if the schema has since changed
+  * Restore the version as of a particular time
+* Thoroughly tested
+* Threadsafe
 
 ## Compatibility
 
-Works with `ActiveRecord` 3+. Note: this code is on the `master` branch and tagged `v4.x`.
-
-Version 3 is on the branch named [`3.0-stable`][9] and is tagged `v3.x`, and works ActiveRecord 4 and ActiveRecord 3.
-
-Version 2 is on the branch named [`2.7-stable`][10] and is tagged `v2.x`, and works with Rails 3.
-
-The Rails 2.3 code is on the [`rails2`][11] branch and tagged `v1.x`. These branches are both stable with their respective versions of Rails but will not have new features added/backported to them.
+| paper_trail | branch     | tags   | ruby     | activerecord |
+| ----------- | ---------- | ------ | -------- | ------------ |
+| 4           | master     | v4.x   | >= 1.8.7 | >= 3.0, < 6  |
+| 3           | 3.0-stable | v3.x   | >= 1.8.7 | >= 3.0, < 5  |
+| 2           | 2.7-stable | v2.x   | >= 1.8.7 | >= 3.0, < 4  |
+| 1           | rails2     | v1.x   | >= 1.8.7 | >= 2.3, < 3  |
 
 ## Installation
 
-### Rails 3 & 4
+### Rails 3 and 4
 
 1. Add PaperTrail to your `Gemfile`.
 
-    `gem 'paper_trail', '~> 4.0.0'`
+    `gem 'paper_trail', '~> 4.0.1'`
 
 2. Generate a migration which will add a `versions` table to your database.
 
@@ -89,7 +93,7 @@ setting up your app with PaperTrail will look something like this:
 
 1. Add PaperTrail to your `Gemfile`.
 
-    `gem 'paper_trail', '~> 4.0.0'`
+    `gem 'paper_trail', '~> 4.0.1'`
 
 2. Generate a migration to add a `versions` table to your database.
 
@@ -435,6 +439,122 @@ class Article < ActiveRecord::Base
 end
 ```
 
+## Turning PaperTrail Off/On
+
+Sometimes you don't want to store changes.  Perhaps you are only interested in
+changes made by your users and don't need to store changes you make yourself in,
+say, a migration -- or when testing your application.
+
+You can turn PaperTrail on or off in three ways: globally, per request, or per
+class.
+
+### Globally
+
+On a global level you can turn PaperTrail off like this:
+
+```ruby
+PaperTrail.enabled = false
+```
+
+For example, you might want to disable PaperTrail in your Rails application's
+test environment to speed up your tests.  This will do it (note: this gets done
+automatically for `RSpec` and `Cucumber`, please see the [Testing
+section](#testing)):
+
+```ruby
+# in config/environments/test.rb
+config.after_initialize do
+  PaperTrail.enabled = false
+end
+```
+
+If you disable PaperTrail in your test environment but want to enable it for
+specific tests, you can add a helper like this to your test helper:
+
+```ruby
+# in test/test_helper.rb
+def with_versioning
+  was_enabled = PaperTrail.enabled?
+  was_enabled_for_controller = PaperTrail.enabled_for_controller?
+  PaperTrail.enabled = true
+  PaperTrail.enabled_for_controller = true
+  begin
+    yield
+  ensure
+    PaperTrail.enabled = was_enabled
+    PaperTrail.enabled_for_controller = was_enabled_for_controller
+  end
+end
+```
+
+And then use it in your tests like this:
+
+```ruby
+test "something that needs versioning" do
+  with_versioning do
+    # your test
+  end
+end
+```
+
+### Per request
+
+You can turn PaperTrail on or off per request by adding a
+`paper_trail_enabled_for_controller` method to your controller which returns
+`true` or `false`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  def paper_trail_enabled_for_controller
+    request.user_agent != 'Disable User-Agent'
+  end
+end
+```
+
+### Per class
+
+If you are about to change some widgets and you don't want a paper trail of your
+changes, you can turn PaperTrail off like this:
+
+```ruby
+Widget.paper_trail_off!
+```
+
+And on again like this:
+
+```ruby
+Widget.paper_trail_on!
+```
+
+### Per method call
+
+You can call a method without creating a new version using `without_versioning`.
+ It takes either a method name as a symbol:
+
+```ruby
+@widget.without_versioning :destroy
+```
+
+Or a block:
+
+```ruby
+@widget.without_versioning do
+  @widget.update_attributes :name => 'Ford'
+end
+```
+
+## Limiting the Number of Versions Created
+
+Configure `version_limit` to cap the number of versions saved per record. This
+does not apply to `create` events.
+
+```ruby
+# Limit: 4 versions per record (3 most recent, plus a `create` event)
+PaperTrail.config.version_limit = 3
+# Remove the limit
+PaperTrail.config.version_limit = nil
+```
+
 ## Reverting And Undeleting A Model
 
 PaperTrail makes reverting to a previous version easy:
@@ -528,6 +648,85 @@ And you can perform `WHERE` queries for object versions based on attributes:
 PaperTrail::Version.where_object(content: "Hello", title: "Article")
 ```
 
+## Diffing Versions
+
+There are two scenarios: diffing adjacent versions and diffing non-adjacent
+versions.
+
+The best way to diff adjacent versions is to get PaperTrail to do it for you.
+If you add an `object_changes` text column to your `versions` table, either at
+installation time with the `rails generate paper_trail:install --with-changes`
+option or manually, PaperTrail will store the `changes` diff (excluding any
+attributes PaperTrail is ignoring) in each `update` version.  You can use the
+`version.changeset` method to retrieve it.  For example:
+
+```ruby
+widget = Widget.create :name => 'Bob'
+widget.versions.last.changeset
+# {
+#   "name"=>[nil, "Bob"],
+#   "created_at"=>[nil, 2015-08-10 04:10:40 UTC],
+#   "updated_at"=>[nil, 2015-08-10 04:10:40 UTC],
+#   "id"=>[nil, 1]
+# }
+widget.update_attributes :name => 'Robert'
+widget.versions.last.changeset
+# {
+#   "name"=>["Bob", "Robert"],
+#   "updated_at"=>[2015-08-10 04:13:19 UTC, 2015-08-10 04:13:19 UTC]
+# }
+widget.destroy
+widget.versions.last.changeset
+# {}
+```
+
+The `object_changes` are only stored for creation and updates, not when an
+object is destroyed.
+
+Please be aware that PaperTrail doesn't use diffs internally.  When I designed
+PaperTrail I wanted simplicity and robustness so I decided to make each version
+of an object self-contained.  A version stores all of its object's data, not a
+diff from the previous version.  This means you can delete any version without
+affecting any other.
+
+To diff non-adjacent versions you'll have to write your own code.  These
+libraries may help:
+
+For diffing two strings:
+
+* [htmldiff][19]: expects but doesn't require HTML input and produces HTML
+  output.  Works very well but slows down significantly on large (e.g. 5,000
+  word) inputs.
+* [differ][20]: expects plain text input and produces plain
+  text/coloured/HTML/any output.  Can do character-wise, word-wise, line-wise,
+  or arbitrary-boundary-string-wise diffs.  Works very well on non-HTML input.
+* [diff-lcs][21]: old-school, line-wise diffs.
+
+For diffing two ActiveRecord objects:
+
+* [Jeremy Weiskotten's PaperTrail fork][22]: uses ActiveSupport's diff to return
+  an array of hashes of the changes.
+* [activerecord-diff][23]: rather like ActiveRecord::Dirty but also allows you
+  to specify which columns to compare.
+
+If you wish to selectively record changes for some models but not others you
+can opt out of recording changes by passing `:save_changes => false` to your
+`has_paper_trail` method declaration.
+
+## Deleting Old Versions
+
+Over time your `versions` table will grow to an unwieldy size.  Because each
+version is self-contained (see the Diffing section above for more) you can
+simply delete any records you don't want any more.  For example:
+
+```sql
+sql> delete from versions where created_at < 2010-06-01;
+```
+
+```ruby
+PaperTrail::Version.delete_all ["created_at < ?", 1.week.ago]
+```
+
 ## Finding Out Who Was Responsible For A Change
 
 If your `ApplicationController` has a `current_user` method, PaperTrail will
@@ -670,6 +869,11 @@ end
 
 ## Associations
 
+**Experimental Feature: Known Issues:**
+[#542](https://github.com/airblade/paper_trail/issues/542),
+[#590](https://github.com/airblade/paper_trail/issues/590).
+See also: Caveats below.
+
 PaperTrail can restore three types of associations: Has-One, Has-Many, and
 Has-Many-Through. In order to do this, you will need to create a
 `version_associations` table, either at installation time with the `rails
@@ -884,7 +1088,7 @@ end
 
 ### Protected Attributes and Metadata
 
-If you are using rails 3 or the [protected_attributes][17] gem you must declare 
+If you are using rails 3 or the [protected_attributes][17] gem you must declare
 your metadata columns to be `attr_accessible`.
 
 ```ruby
@@ -900,164 +1104,6 @@ end
 If you're using [strong_parameters][18] instead of [protected_attributes][17]
 then there is no need to use `attr_accessible`.
 
-## Diffing Versions
-
-There are two scenarios: diffing adjacent versions and diffing non-adjacent
-versions.
-
-The best way to diff adjacent versions is to get PaperTrail to do it for you.
-If you add an `object_changes` text column to your `versions` table, either at
-installation time with the `rails generate paper_trail:install --with-changes`
-option or manually, PaperTrail will store the `changes` diff (excluding any
-attributes PaperTrail is ignoring) in each `update` version.  You can use the
-`version.changeset` method to retrieve it.  For example:
-
-```ruby
-widget = Widget.create :name => 'Bob'
-widget.versions.last.changeset                # {'name' => [nil, 'Bob']}
-widget.update_attributes :name => 'Robert'
-widget.versions.last.changeset                # {'name' => ['Bob', 'Robert']}
-widget.destroy
-widget.versions.last.changeset                # {}
-```
-
-Note PaperTrail only stores the changes for creation and updates; it doesn't
-store anything when an object is destroyed.
-
-Please be aware that PaperTrail doesn't use diffs internally.  When I designed
-PaperTrail I wanted simplicity and robustness so I decided to make each version
-of an object self-contained.  A version stores all of its object's data, not a
-diff from the previous version.  This means you can delete any version without
-affecting any other.
-
-To diff non-adjacent versions you'll have to write your own code.  These
-libraries may help:
-
-For diffing two strings:
-
-* [htmldiff][19]: expects but doesn't require HTML input and produces HTML
-  output.  Works very well but slows down significantly on large (e.g. 5,000
-  word) inputs.
-* [differ][20]: expects plain text input and produces plain
-  text/coloured/HTML/any output.  Can do character-wise, word-wise, line-wise,
-  or arbitrary-boundary-string-wise diffs.  Works very well on non-HTML input.
-* [diff-lcs][21]: old-school, line-wise diffs.
-
-For diffing two ActiveRecord objects:
-
-* [Jeremy Weiskotten's PaperTrail fork][22]: uses ActiveSupport's diff to return
-  an array of hashes of the changes.
-* [activerecord-diff][23]: rather like ActiveRecord::Dirty but also allows you
-  to specify which columns to compare.
-
-If you wish to selectively record changes for some models but not others you
-can opt out of recording changes by passing `:save_changes => false` to your
-`has_paper_trail` method declaration.
-
-## Turning PaperTrail Off/On
-
-Sometimes you don't want to store changes.  Perhaps you are only interested in
-changes made by your users and don't need to store changes you make yourself in,
-say, a migration -- or when testing your application.
-
-You can turn PaperTrail on or off in three ways: globally, per request, or per
-class.
-
-### Globally
-
-On a global level you can turn PaperTrail off like this:
-
-```ruby
-PaperTrail.enabled = false
-```
-
-For example, you might want to disable PaperTrail in your Rails application's
-test environment to speed up your tests.  This will do it (note: this gets done
-automatically for `RSpec` and `Cucumber`, please see the [Testing
-section](#testing)):
-
-```ruby
-# in config/environments/test.rb
-config.after_initialize do
-  PaperTrail.enabled = false
-end
-```
-
-If you disable PaperTrail in your test environment but want to enable it for
-specific tests, you can add a helper like this to your test helper:
-
-```ruby
-# in test/test_helper.rb
-def with_versioning
-  was_enabled = PaperTrail.enabled?
-  was_enabled_for_controller = PaperTrail.enabled_for_controller?
-  PaperTrail.enabled = true
-  PaperTrail.enabled_for_controller = true
-  begin
-    yield
-  ensure
-    PaperTrail.enabled = was_enabled
-    PaperTrail.enabled_for_controller = was_enabled_for_controller
-  end
-end
-```
-
-And then use it in your tests like this:
-
-```ruby
-test "something that needs versioning" do
-  with_versioning do
-    # your test
-  end
-end
-```
-
-### Per request
-
-You can turn PaperTrail on or off per request by adding a
-`paper_trail_enabled_for_controller` method to your controller which returns
-`true` or `false`:
-
-```ruby
-class ApplicationController < ActionController::Base
-  def paper_trail_enabled_for_controller
-    request.user_agent != 'Disable User-Agent'
-  end
-end
-```
-
-### Per class
-
-If you are about to change some widgets and you don't want a paper trail of your
-changes, you can turn PaperTrail off like this:
-
-```ruby
-Widget.paper_trail_off!
-```
-
-And on again like this:
-
-```ruby
-Widget.paper_trail_on!
-```
-
-### Per method call
-
-You can call a method without creating a new version using `without_versioning`.
- It takes either a method name as a symbol:
-
-```ruby
-@widget.without_versioning :destroy
-```
-
-Or a block:
-
-```ruby
-@widget.without_versioning do
-  @widget.update_attributes :name => 'Ford'
-end
-```
-
 ## Using a custom serializer
 
 By default, PaperTrail stores your changes as a `YAML` dump. You can override
@@ -1091,6 +1137,17 @@ end
 Note: You don't need to use a particular serializer for the PostgreSQL `JSON`
 column type.
 
+#### Convert a column from text to json
+
+Postgres' `alter column` command will not automatically convert a `text`
+column to `json`, but it can still be done with plain SQL.
+
+```sql
+alter table versions
+alter column object type json
+using object::json;
+```
+
 ## SerializedAttributes support
 
 PaperTrail has a config option that can be used to enable/disable whether
@@ -1110,32 +1167,6 @@ PaperTrail.config.serialized_attributes = false
 PaperTrail.serialized_attributes?
 ```
 
-## Limiting the Number of Versions Created
-
-Configure `version_limit` to cap the number of versions saved per record. This
-does not apply to `create` events.
-
-```ruby
-# Limit: 4 versions per record (3 most recent, plus a `create` event)
-PaperTrail.config.version_limit = 3
-# Remove the limit
-PaperTrail.config.version_limit = nil
-```
-
-## Deleting Old Versions
-
-Over time your `versions` table will grow to an unwieldy size.  Because each
-version is self-contained (see the Diffing section above for more) you can
-simply delete any records you don't want any more.  For example:
-
-```sql
-sql> delete from versions where created_at < 2010-06-01;
-```
-
-```ruby
-PaperTrail::Version.delete_all ["created_at < ?", 1.week.ago]
-```
-
 ## Testing
 
 You may want to turn PaperTrail off to speed up your tests.  See the [Turning