Allow incompatible versions of ActiveRecord

For advanced users only. A warning is produced. See discussion
in paper_trail/compatibility.rb

CHANGELOG.md

@@ -17,6 +17,11 @@ recommendations of [keepachangelog.com](http://keepachangelog.com/).
 
 - None
 
+### Dependencies
+
+- Allow contributors to install incompatible versions of ActiveRecord.
+  See discussion in paper_trail/compatibility.rb 
+
 ## 10.3.0 (2019-04-09)
 
 ### Breaking Changes

lib/paper_trail.rb

@@ -16,6 +16,7 @@ require "active_record"
 
 require "request_store"
 require "paper_trail/cleaner"
+require "paper_trail/compatibility"
 require "paper_trail/config"
 require "paper_trail/has_paper_trail"
 require "paper_trail/record_history"
@@ -145,3 +146,7 @@ if defined?(::Rails)
 else
   require "paper_trail/frameworks/active_record"
 end
+
+if defined?(::ActiveRecord)
+  ::PaperTrail::Compatibility.check_activerecord(::ActiveRecord.gem_version)
+end

lib/paper_trail/compatibility.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  # Rails does not follow SemVer, makes breaking changes in minor versions.
+  # Breaking changes are expected, and are generally good for the rails
+  # ecosystem. However, they often require dozens of hours to fix, even with the
+  # [help of experts](https://github.com/paper-trail-gem/paper_trail/pull/899).
+  #
+  # It is not safe to assume that a new version of rails will be compatible with
+  # PaperTrail. PT is only compatible with the versions of rails that it is
+  # tested against. See `.travis.yml`.
+  #
+  # However, as of
+  # [#1213](https://github.com/paper-trail-gem/paper_trail/pull/1213) our
+  # gemspec allows installation with newer, incompatible rails versions. We hope
+  # this will make it easier for contributors to work on compatibility with
+  # newer rails versions. Most PT users should avoid incompatible rails
+  # versions.
+  module Compatibility
+    ACTIVERECORD_GTE = ">= 4.2"
+    ACTIVERECORD_LT = "< 6.1"
+
+    E_INCOMPATIBLE_AR = <<-EOS
+      PaperTrail %s is not compatible with ActiveRecord %s. We allow PT
+      contributors to install incompatible versions of ActiveRecord, and this
+      warning can be silenced with an environment variable, but this is a bad
+      idea for normal use. Please install a compatible version of ActiveRecord
+      instead (%s). Please see the discussion in paper_trail/compatibility.rb
+      for details.
+    EOS
+
+    # Normal users need a warning if they accidentally install an incompatible
+    # version of ActiveRecord. Contributors can silence this warning with an
+    # environment variable.
+    def self.check_activerecord(ar_version)
+      raise ::TypeError unless ar_version.instance_of?(::Gem::Version)
+      return if ::ENV["PT_SILENCE_AR_COMPAT_WARNING"].present?
+      req = ::Gem::Requirement.new([ACTIVERECORD_GTE, ACTIVERECORD_LT])
+      unless req.satisfied_by?(ar_version)
+        ::Kernel.warn(
+          format(
+            E_INCOMPATIBLE_AR,
+            ::PaperTrail.gem_version,
+            ar_version,
+            req
+          )
+        )
+      end
+    end
+  end
+end

paper_trail.gemspec

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 $LOAD_PATH.unshift File.expand_path("lib", __dir__)
+require "paper_trail/compatibility"
 require "paper_trail/version_number"
 
 Gem::Specification.new do |s|
@@ -27,8 +28,9 @@ has been destroyed.
   s.required_rubygems_version = ">= 1.3.6"
   s.required_ruby_version = ">= 2.3.0"
 
-  # Rails does not follow semver, makes breaking changes in minor versions.
-  s.add_dependency "activerecord", [">= 4.2", "< 6.1"]
+  # We no longer specify a maximum rails version.
+  # See discussion in paper_trail/compatibility.rb
+  s.add_dependency "activerecord", ::PaperTrail::Compatibility::ACTIVERECORD_GTE
   s.add_dependency "request_store", "~> 1.1"
 
   s.add_development_dependency "appraisal", "~> 2.2"

spec/paper_trail/compatibility_spec.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  ::RSpec.describe(Compatibility) do
+    describe ".check_activerecord" do
+      context "when compatible" do
+        it "does not produce output" do
+          ar_version = ::Gem::Version.new("6.0.0")
+          expect {
+            described_class.check_activerecord(ar_version)
+          }.not_to output.to_stderr
+        end
+      end
+
+      context "when incompatible" do
+        it "writes a warning to stderr" do
+          ar_version = ::Gem::Version.new("6.1.0")
+          expect {
+            described_class.check_activerecord(ar_version)
+          }.to output(/not compatible/).to_stderr
+        end
+      end
+    end
+  end
+end