From 1b046a03393b86d62262139d87386de4e9ca8061 Mon Sep 17 00:00:00 2001
From: Jared Beck <jared@jaredbeck.com>
Date: Sun, 28 Jul 2019 00:15:42 -0400
Subject: [PATCH] Allow incompatible versions of ActiveRecord

For advanced users only. A warning is produced. See discussion
in paper_trail/compatibility.rb
---
 CHANGELOG.md                           |  5 +++
 lib/paper_trail.rb                     |  7 ++++
 lib/paper_trail/compatibility.rb       | 51 ++++++++++++++++++++++++++
 paper_trail.gemspec                    |  6 ++-
 spec/paper_trail/compatibility_spec.rb | 25 +++++++++++++
 5 files changed, 92 insertions(+), 2 deletions(-)
 create mode 100644 lib/paper_trail/compatibility.rb
 create mode 100644 spec/paper_trail/compatibility_spec.rb

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ddd45924b..466e6cb71 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/lib/paper_trail.rb b/lib/paper_trail.rb
index ed9daa7dc..097478423 100644
--- a/lib/paper_trail.rb
+++ b/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
diff --git a/lib/paper_trail/compatibility.rb b/lib/paper_trail/compatibility.rb
new file mode 100644
index 000000000..16f1d7558
--- /dev/null
+++ b/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
diff --git a/paper_trail.gemspec b/paper_trail.gemspec
index 1511296e4..a7f958770 100644
--- a/paper_trail.gemspec
+++ b/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"
diff --git a/spec/paper_trail/compatibility_spec.rb b/spec/paper_trail/compatibility_spec.rb
new file mode 100644
index 000000000..d2dfb23e8
--- /dev/null
+++ b/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