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 "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,9 @@ def version
 else
  require "paper_trail/frameworks/active_record"
 end
+
+if defined?(::ActiveRecord)
+ ::PaperTrail::Compatibility.check_activerecord(
+ ::Gem::Version.new(::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