Docs: Update changelog and readme re: #1143

[ci skip]

CHANGELOG.md

@@ -45,7 +45,12 @@ respectively.
 ### Fixed
 
 - [#594](https://github.com/paper-trail-gem/paper_trail/issues/594) -
-  A long-standing issue with reification of STI subclasses
+  A rare issue with reification of STI subclasses, affecting only PT-AT users
+  who have a model with mutliple associations, whose foreign keys are named the
+  same, and whose foreign models are STI with the same parent class. This fix
+  requires a schema change. See [docs section 4.b.1 The optional `item_subtype`
+  column](https://github.com/paper-trail-gem/paper_trail#4b-associations) for
+  instructions.
 
 ## 9.2.0 (2018-06-09)
 

README.md

@@ -850,6 +850,24 @@ you must add it to your own `Gemfile`. We will keep PT-AT as a development
 dependency and continue running the existing tests related to association
 tracking for as long as is practical.
 
+#### 4.b.1 The optional `item_subtype` column
+
+As of PT 10, users may add an `item_subtype` column to their `versions` table.
+When storing versions for STI models, rails stores the base class in `item_type`
+(that's just how polymorphic associations like `item` work) In addition, PT will
+now store the subclass in `item_subtype`. If this column is present PT-AT will
+use it to fix a rare issue with reification of STI subclasses.
+
+```ruby
+add_column :versions, :item_subtype, null: true
+```
+
+So, if you use PT-AT and STI, the addition of this colulmn is recommended.
+
+- https://github.com/paper-trail-gem/paper_trail/issues/594
+- https://github.com/paper-trail-gem/paper_trail/pull/1143
+- https://github.com/westonganger/paper_trail-association_tracking/pull/5
+
 ### 4.c. Storing Metadata
 
 You can add your own custom columns to your `versions` table. Values can be

spec/models/person_spec.rb

@@ -167,6 +167,11 @@ RSpec.describe Person, type: :model, versioning: true do
       expect(person.reload.versions.length).to(eq(3))
 
       # These will work when PT-AT adds support for the new `item_subtype` column
+      #
+      # - https://github.com/westonganger/paper_trail-association_tracking/pull/5
+      # - https://github.com/paper-trail-gem/paper_trail/pull/1143
+      # - https://github.com/paper-trail-gem/paper_trail/issues/594
+      #
       # second_version = person.reload.versions.second.reify(has_one: true)
       # expect(second_version.car.name).to(eq("BMW 325"))
       # expect(second_version.bicycle.name).to(eq("BMX 1.0"))