paper_trail 7.0.0 → 7.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c3a67c57c19665911311eab6dc66bd670e390f57
-  data.tar.gz: f74e8562ba1ac3e305d5785e50fc1357ee0a69ca
+  metadata.gz: 4e92a25394990bd883a845f051763e117abd5d35
+  data.tar.gz: bde729a85a1052106a116e930f3afafdde5ca319
 SHA512:
-  metadata.gz: 8e493b2ef87fb52d53c54cefa55369ee31ac82261d30dac5833bc4d010aeff5387fd9362deef390b97e7b646bc22fbbaeb5ea2620d63cc2369e5e9ddcd78744e
-  data.tar.gz: 4cb5a0c791d890011e9aff19d0e8119955e43d8aab22a2bd57f5c7c9457dd5dc60345d79494aedf87e254dd3dde524832b04e2baeeca4eaedc1b7e1f91b5b893
+  metadata.gz: 7f2d6eba98c56942424310f2a3cc0c855c264eecc17fa0377dbb4bdad0ed0e15d66190e1043671af4c2f35c9605f0707565bdada142c1a5f8ce6b3eac203c8e3
+  data.tar.gz: 99b7dd59468398c88e7c15f4e8b4fa6a2ba274a1aa8794a2caa8351d54cf6abdc51908449d26e71382b0505f08bcd0cdfbaa8fa2a030f9a76a391e84daafc8db

data/.rubocop_todo.yml

@@ -27,8 +27,5 @@ RSpec/MessageSpies:
 RSpec/NamedSubject:
   Enabled: false
 
-RSpec/NestedGroups:
-  Max: 5 # goal: 3
-
 Security/YAMLLoad:
   Enabled: false

data/CHANGELOG.md

@@ -17,6 +17,21 @@ recommendations of [keepachangelog.com](http://keepachangelog.com/).
 
 - None
 
+## 7.0.1 (2017-04-10)
+
+### Breaking Changes
+
+- None
+
+### Added
+
+- Generate cleaner migrations for databases other than MySQL
+
+### Fixed
+
+- [#949](https://github.com/airblade/paper_trail/issues/949) - Inherit from the
+  new versioned migration class, e.g. `ActiveRecord::Migration[5.1]`
+
 ## 7.0.0 (2017-04-01)
 
 ### Breaking Changes

data/README.md

@@ -11,7 +11,7 @@ has been destroyed.
 | Version        | Documentation |
 | -------------- | ------------- |
 | Unreleased     | https://github.com/airblade/paper_trail/blob/master/README.md |
-| 7.0.0          | https://github.com/airblade/paper_trail/blob/v7.0.0/README.md |
+| 7.0.1          | https://github.com/airblade/paper_trail/blob/v7.0.0/README.md |
 | 6.0.2          | https://github.com/airblade/paper_trail/blob/v6.0.2/README.md |
 | 5.2.3          | https://github.com/airblade/paper_trail/blob/v5.2.3/README.md |
 | 4.2.0          | https://github.com/airblade/paper_trail/blob/v4.2.0/README.md |
@@ -677,7 +677,7 @@ For diffing two ActiveRecord objects:
 * [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
+If you want 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.
 
@@ -1151,11 +1151,12 @@ class Post < ActiveRecord::Base
 
   # Existing versions method.  We don't want to clash.
   def versions
-    ...
+    # ...
   end
+
   # Existing version method.  We don't want to clash.
   def version
-    ...
+    # ...
   end
 end
 ```
@@ -1183,10 +1184,10 @@ If you use PostgreSQL, and would like to store your `object` (and/or
 
 ```ruby
 create_table :versions do |t|
-  ...
+  # ...
   t.json :object          # Full object changes
   t.json :object_changes  # Optional column-level changes
-  ...
+  # ...
 end
 ```
 
@@ -1331,13 +1332,13 @@ ENV["RAILS_ENV"] ||= 'test'
 require 'spec_helper'
 require File.expand_path("../../config/environment", __FILE__)
 require 'rspec/rails'
-...
+# ...
 require 'paper_trail/frameworks/rspec'
 ```
 
 With the helper loaded, PaperTrail will be turned off for all tests by
 default. To enable PaperTrail for a test you can either wrap the
-test in a `with_versioning` block, or pass in `:versioning => true` option to a
+test in a `with_versioning` block, or pass in `versioning: true` option to a
 spec block.
 
 ```ruby
@@ -1352,7 +1353,7 @@ describe "RSpec test group" do
     end
   end
 
-  it 'can be turned on at the `it` or `describe` level like this', :versioning => true do
+  it 'can be turned on at the `it` or `describe` level', versioning: true do
     expect(PaperTrail).to be_enabled
   end
 end
@@ -1389,37 +1390,37 @@ describe Widget do
 end
 ```
 
-It is also possible to do assertions on the versions using `have_a_version_with` matcher.
+#### Matchers
+
+The `have_a_version_with` matcher makes assertions about versions using
+`where_object`, based on the `object` column.
 
 ```ruby
 describe '`have_a_version_with` matcher' do
-  before do
+  it "is possible to do assertions on version attributes" do
     widget.update_attributes!(name: 'Leonard', an_integer: 1)
     widget.update_attributes!(name: 'Tom')
     widget.update_attributes!(name: 'Bob')
-  end
-
-  it "is possible to do assertions on version attributes" do
     expect(widget).to have_a_version_with name: 'Leonard', an_integer: 1
     expect(widget).to have_a_version_with an_integer: 1
     expect(widget).to have_a_version_with name: 'Tom'
   end
 end
 ```
-There is also a `have_a_version_with_changes` matcher. This is only usable if your versions table [has an `object_changes` column for storing changesets](#3c-diffing-versions).
+
+The `have_a_version_with_changes` matcher makes assertions about versions using
+`where_object_changes`, based on the optional
+[`object_changes` column](#3c-diffing-versions).
 
 ```ruby
 describe '`have_a_version_with_changes` matcher' do
-  before do
+  it "is possible to do assertions on version changes" do
     widget.update_attributes!(name: 'Leonard', an_integer: 1)
     widget.update_attributes!(name: 'Tom')
     widget.update_attributes!(name: 'Bob')
-  end
-
-  it "is possible to do assertions on version changes" do
-    expect(widget).to have_a_version_with name: 'Leonard', an_integer: 2
-    expect(widget).to have_a_version_with an_integer: 2
-    expect(widget).to have_a_version_with name: 'Bob'
+    expect(widget).to have_a_version_with_changes name: 'Leonard', an_integer: 2
+    expect(widget).to have_a_version_with_changes an_integer: 2
+    expect(widget).to have_a_version_with_changes name: 'Bob'
   end
 end
 ```
@@ -1430,7 +1431,7 @@ For more examples of the RSpec matchers, see the
 ### 7.c. Cucumber
 
 PaperTrail provides a helper for [Cucumber][28] that works similar to the RSpec
-helper.If you wish to use the helper, you will need to require in your cucumber
+helper. If you want to use the helper, you will need to require in your cucumber
 helper like so:
 
 ```ruby
@@ -1438,12 +1439,12 @@ helper like so:
 
 ENV["RAILS_ENV"] ||= "cucumber"
 require File.expand_path(File.dirname(__FILE__) + '/../../config/environment')
-...
+# ...
 require 'paper_trail/frameworks/cucumber'
 ```
 
 When the helper is loaded, PaperTrail will be turned off for all scenarios by a
-`before` hook added by the helper by default. When you wish to enable PaperTrail
+`before` hook added by the helper by default. When you want to enable PaperTrail
 for a scenario, you can wrap code in a `with_versioning` block in a step, like
 so:
 
@@ -1462,7 +1463,7 @@ value to `{}` as well, again, to help prevent data spillover between tests.
 
 ### 7.d. Spork
 
-If you wish to use the `RSpec` or `Cucumber` helpers with [Spork][29], you will
+If you want to use the `RSpec` or `Cucumber` helpers with [Spork][29], you will
 need to manually require the helper(s) in your `prefork` block on your test
 helper, like so:
 
@@ -1479,13 +1480,13 @@ Spork.prefork do
   require 'rspec/rails'
   require 'paper_trail/frameworks/rspec'
   require 'paper_trail/frameworks/cucumber'
-  ...
+  # ...
 end
 ```
 
 ### 7.e. Zeus or Spring
 
-If you wish to use the `RSpec` or `Cucumber` helpers with [Zeus][30] or
+If you want to use the `RSpec` or `Cucumber` helpers with [Zeus][30] or
 [Spring][31], you will need to manually require the helper(s) in your test
 helper, like so:
 

data/lib/generators/paper_trail/install_generator.rb

@@ -6,6 +6,14 @@ module PaperTrail
   class InstallGenerator < ::Rails::Generators::Base
     include ::Rails::Generators::Migration
 
+    # Class names of MySQL adapters.
+    # - `MysqlAdapter` - Used by gems: `mysql`, `activerecord-jdbcmysql-adapter`.
+    # - `Mysql2Adapter` - Used by `mysql2` gem.
+    MYSQL_ADAPTERS = [
+      "ActiveRecord::ConnectionAdapters::MysqlAdapter",
+      "ActiveRecord::ConnectionAdapters::Mysql2Adapter"
+    ].freeze
+
     source_root File.expand_path("../templates", __FILE__)
     class_option(
       :with_changes,
@@ -50,7 +58,57 @@ module PaperTrail
       if self.class.migration_exists?(migration_dir, template)
         ::Kernel.warn "Migration already exists: #{template}"
       else
-        migration_template "#{template}.rb", "db/migrate/#{template}.rb"
+        migration_template(
+          "#{template}.rb.erb",
+          "db/migrate/#{template}.rb",
+          item_type_options: item_type_options,
+          migration_version: migration_version,
+          versions_table_options: versions_table_options
+        )
+      end
+    end
+
+    private
+
+    # MySQL 5.6 utf8mb4 limit is 191 chars for keys used in indexes.
+    # See https://github.com/airblade/paper_trail/issues/651
+    def item_type_options
+      opt = { null: false }
+      opt[:limit] = 191 if mysql?
+      ", #{opt}"
+    end
+
+    def migration_version
+      major = ActiveRecord::VERSION::MAJOR
+      if major >= 5
+        "[#{major}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+
+    def mysql?
+      MYSQL_ADAPTERS.include?(ActiveRecord::Base.connection.class.name)
+    end
+
+    # Even modern versions of MySQL still use `latin1` as the default character
+    # encoding. Many users are not aware of this, and run into trouble when they
+    # try to use PaperTrail in apps that otherwise tend to use UTF-8. Postgres, by
+    # comparison, uses UTF-8 except in the unusual case where the OS is configured
+    # with a custom locale.
+    #
+    # - https://dev.mysql.com/doc/refman/5.7/en/charset-applications.html
+    # - http://www.postgresql.org/docs/9.4/static/multibyte.html
+    #
+    # Furthermore, MySQL's original implementation of UTF-8 was flawed, and had
+    # to be fixed later by introducing a new charset, `utf8mb4`.
+    #
+    # - https://mathiasbynens.be/notes/mysql-utf8mb4
+    # - https://dev.mysql.com/doc/refman/5.5/en/charset-unicode-utf8mb4.html
+    #
+    def versions_table_options
+      if mysql?
+        ', { options: "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci" }'
+      else
+        ""
       end
     end
   end

data/lib/generators/paper_trail/templates/create_versions.rb.erb

@@ -0,0 +1,36 @@
+# This migration creates the `versions` table, the only schema PT requires.
+# All other migrations PT provides are optional.
+class CreateVersions < ActiveRecord::Migration<%= migration_version %>
+
+  # The largest text column available in all supported RDBMS is
+  # 1024^3 - 1 bytes, roughly one gibibyte.  We specify a size
+  # so that MySQL will use `longtext` instead of `text`.  Otherwise,
+  # when serializing very large objects, `text` might not be big enough.
+  TEXT_BYTES = 1_073_741_823
+
+  def change
+    create_table :versions<%= versions_table_options %> do |t|
+      t.string   :item_type<%= item_type_options %>
+      t.integer  :item_id,   null: false
+      t.string   :event,     null: false
+      t.string   :whodunnit
+      t.text     :object, limit: TEXT_BYTES
+
+      # Known issue in MySQL: fractional second precision
+      # -------------------------------------------------
+      #
+      # MySQL timestamp columns do not support fractional seconds unless
+      # defined with "fractional seconds precision". MySQL users should manually
+      # add fractional seconds precision to this migration, specifically, to
+      # the `created_at` column.
+      # (https://dev.mysql.com/doc/refman/5.6/en/fractional-seconds.html)
+      #
+      # MySQL users should also upgrade to rails 4.2, which is the first
+      # version of ActiveRecord with support for fractional seconds in MySQL.
+      # (https://github.com/rails/rails/pull/14359)
+      #
+      t.datetime :created_at
+    end
+    add_index :versions, %i(item_type item_id)
+  end
+end

data/lib/paper_trail/version_number.rb

@@ -7,7 +7,7 @@ module PaperTrail
   module VERSION
     MAJOR = 7
     MINOR = 0
-    TINY = 0
+    TINY = 1
     PRE = nil
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".").freeze

data/paper_trail.gemspec

@@ -41,7 +41,7 @@ has been destroyed.
   s.add_development_dependency "generator_spec", "~> 0.9.3"
   s.add_development_dependency "database_cleaner", "~> 1.2"
   s.add_development_dependency "pry-nav", "~> 0.2.4"
-  s.add_development_dependency "rubocop", "~> 0.48.0"
+  s.add_development_dependency "rubocop", "0.48.0"
   s.add_development_dependency "rubocop-rspec", "~> 1.15.0"
   s.add_development_dependency "timecop", "~> 0.8.0"
   s.add_development_dependency "sqlite3", "~> 1.2"

data/spec/generators/install_generator_spec.rb

@@ -15,14 +15,30 @@ RSpec.describe PaperTrail::InstallGenerator, type: :generator do
     end
 
     it "generates a migration for creating the 'versions' table" do
+      expected_parent_class = lambda {
+        old_school = "ActiveRecord::Migration"
+        ar_version = ActiveRecord::VERSION
+        if ar_version::MAJOR >= 5
+          format("%s[%d.%d]", old_school, ar_version::MAJOR, ar_version::MINOR)
+        else
+          old_school
+        end
+      }.call
+      expected_create_table_options = lambda {
+        if described_class::MYSQL_ADAPTERS.include?(ActiveRecord::Base.connection.class.name)
+          ', { options: "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci" }'
+        else
+          ""
+        end
+      }.call
       expect(destination_root).to(
         have_structure {
           directory("db") {
             directory("migrate") {
               migration("create_versions") {
-                contains "class CreateVersions"
+                contains("class CreateVersions < " + expected_parent_class)
                 contains "def change"
-                contains "create_table :versions"
+                contains "create_table :versions#{expected_create_table_options}"
               }
             }
           }

data/spec/models/boolit_spec.rb

@@ -1,48 +1,40 @@
 require "rails_helper"
 require Rails.root.join("..", "custom_json_serializer")
 
-describe Boolit, type: :model do
-  it { is_expected.to be_versioned }
+RSpec.describe Boolit, type: :model, versioning: true do
+  subject { Boolit.create! }
 
-  it "has a default scope" do
-    expect(subject.default_scopes).not_to be_empty
+  before { subject.update_attributes!(name: FFaker::Name.name) }
+
+  it "has two versions" do
+    expect(subject.versions.size).to eq(2)
   end
 
-  describe "Versioning", versioning: true do
-    subject { Boolit.create! }
+  it "can be reified and persisted" do
+    expect { subject.versions.last.reify.save! }.not_to raise_error
+  end
 
-    before { subject.update_attributes!(name: FFaker::Name.name) }
+  context "Instance falls out of default scope" do
+    before { subject.update_attributes!(scoped: false) }
 
-    it "has two versions" do
-      expect(subject.versions.size).to eq(2)
+    it "is NOT scoped" do
+      expect(Boolit.first).to be_nil
     end
 
-    it "can be reified and persisted" do
-      expect { subject.versions.last.reify.save! }.not_to raise_error
+    it "still can be reified and persisted" do
+      expect { subject.paper_trail.previous_version.save! }.not_to raise_error
     end
 
-    context "Instance falls out of default scope" do
-      before { subject.update_attributes!(scoped: false) }
-
-      it "is NOT scoped" do
-        expect(Boolit.first).to be_nil
-      end
-
-      it "still can be reified and persisted" do
-        expect { subject.paper_trail.previous_version.save! }.not_to raise_error
+    context "with `nil` attributes on the live instance" do
+      before do
+        PaperTrail.serializer = CustomJsonSerializer
+        subject.update_attributes!(name: nil)
+        subject.update_attributes!(name: FFaker::Name.name)
       end
+      after { PaperTrail.serializer = PaperTrail::Serializers::YAML }
 
-      context "with `nil` attributes on the live instance" do
-        before do
-          PaperTrail.serializer = CustomJsonSerializer
-          subject.update_attributes!(name: nil)
-          subject.update_attributes!(name: FFaker::Name.name)
-        end
-        after { PaperTrail.serializer = PaperTrail::Serializers::YAML }
-
-        it "does not overwrite that attribute during the reification process" do
-          expect(subject.paper_trail.previous_version.name).to be_nil
-        end
+      it "does not overwrite that attribute during the reification process" do
+        expect(subject.paper_trail.previous_version.name).to be_nil
       end
     end
   end