Skip to content

Commit 285e024

Browse files
westongangerwestonganger
committed
improve README
1 parent eae5ccf commit 285e024

File tree

1 file changed

+83
-80
lines changed

1 file changed

+83
-80
lines changed

‎README.md‎

Lines changed: 83 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,46 @@
1-
# [WIP] paper_trail-association_tracking
1+
# PaperTrail-AssociationTracking
22

33
[![Build Status][1]][2]
44

5-
Plugin for the PaperTrail gem to track and reify associations
5+
Plugin for the [PaperTrail](https://github.com/paper-trail-gem/paper_trail.git) gem to track and reify associations.
6+
7+
**PR's will happily be accepted**
8+
9+
This gem was extracted from PaperTrail in v10 to simplify things in PaperTrail and association tracking seperately.
10+
At this time, `paper_trail` has a runtime dependency on this gem and will keep running the existing tests related
11+
to association tracking. This arrangement will be maintained for a few years, if practical.
12+
13+
A little history lesson, discussed as early as 2009, and first implemented in late 2014, association
14+
tracking was part of PT core until 2018 as an experimental feature and was use at your own risk. This gem now
15+
maintains a list of known issues and we hope the community can help remove some of them via PR's.
616

717
## TODO
818

919
- Continue removing most-non association specs
10-
- Improve Readme
1120
- Add consolidated list of paper trail plugins to paper_trail core readme
1221

1322
## Table of Contents
1423

1524
<!-- toc -->
1625

17-
- [1. Install](#1-install)
18-
- [2. Associations](#2-associations)
19-
- [3. Known Issues](#3-known-issues)
20-
- [Articles](#articles)
26+
- [Install](#install)
27+
- [Associations](#associations)
28+
- [Known Issues](#known-issues)
2129
- [Contributing](#contributing)
2230
- [Credits](#credits)
2331

2432
<!-- tocstop -->
2533

26-
### 1. Install
27-
28-
1. Add to your `Gemfile`.
34+
# Install
2935

3036
```ruby
37+
# Gemfile
38+
3139
gem 'paper_trail' # Requires v10+
3240
gem 'paper_trail-association_tracking'
3341
```
3442

35-
### 2. Association Tracking
43+
# Association Tracking
3644

3745
This plugin currently can restore three types of associations: Has-One, Has-Many, and
3846
Has-Many-Through. In order to do this, you will need to do two things:
@@ -83,7 +91,7 @@ t.amount # 100
8391
t.location.latitude # 12.345
8492
```
8593

86-
If the parent and child are updated in one go, PaperTrail can use the
94+
If the parent and child are updated in one go, PaperTrail-AssociationTracking can use the
8795
aforementioned `transaction_id` to reify the models as they were before the
8896
transaction (instead of before the update to the model).
8997

@@ -101,7 +109,7 @@ t.amount # 100
101109
t.location.latitude # 12.345, instead of 54.321
102110
```
103111

104-
By default, PaperTrail excludes an associated record from the reified parent
112+
By default, PaperTrail-AssociationTracking excludes an associated record from the reified parent
105113
model if the associated record exists in the live model but did not exist as at
106114
the time the version was created. This is usually what you want if you just want
107115
to look at the reified version. But if you want to persist it, it would be
@@ -133,118 +141,113 @@ widget_0.save!
133141
widget.reload.wotsit # nil
134142
```
135143

136-
#### 3. Known Issues
144+
# Known Issues
145+
146+
Associations have the following known issues, in order of descending importance. Use in Production at your own risk.
147+
148+
**PR's for these issues will happily be accepted**
137149

138-
Associations are an **experimental feature** and have the following known
139-
issues, in order of descending importance. Use in Production at your own risk.
150+
If you notice anything here that should be updated/removed/edited feel free to create an issue.
140151

141-
1. PaperTrail only reifies the first level of associations.
152+
1. PaperTrail-AssociationTracking only reifies the first level of associations.
142153
1. Sometimes the has_one association will find more than one possible candidate and will raise a `PaperTrail::Reifiers::HasOne::FoundMoreThanOne` error. For example, see `spec/models/person_spec.rb`
143-
- If you are not using STI, you may want to just assume the first result (of multiple) is the correct one and continue. Versions pre v8.1.2 and below did this without error or warning. To do so add the following line to your initializer: `PaperTrail.config.association_reify_error_behaviour = :warn`. Valid options are: `[:error, :warn, :ignore]`
154+
- If you are not using STI, you may want to just assume the first result (of multiple) is the correct one and continue. PaperTrail <= v8 did this without error or warning. To do so add the following line to your initializer: `PaperTrail.config.association_reify_error_behaviour = :warn`. Valid options are: `[:error, :warn, :ignore]`
144155
- When using STI, even if you enable `:warn` you will likely still end up recieving an `ActiveRecord::AssociationTypeMismatch` error.
145-
1. [#542](https://github.com/airblade/paper_trail/issues/542) -
156+
1. [PT Issue #542](https://github.com/airblade/paper_trail/issues/542) -
146157
Not compatible with [transactional tests](https://github.com/rails/rails/blob/591a0bb87fff7583e01156696fbbf929d48d3e54/activerecord/lib/active_record/fixtures.rb#L142), aka. transactional fixtures.
147158
1. Requires database timestamp columns with fractional second precision.
148159
- Sqlite and postgres timestamps have fractional second precision by default.
149160
[MySQL timestamps do not](https://dev.mysql.com/doc/refman/5.6/en/fractional-seconds.html). Furthermore, MySQL 5.5 and earlier do not
150161
support fractional second precision at all.
151162
- Also, support for fractional seconds in MySQL was not added to
152163
rails until ActiveRecord 4.2 (https://github.com/rails/rails/pull/14359).
153-
1. PaperTrail can't restore an association properly if the association record
164+
1. PaperTrail-AssociationTracking can't restore an association properly if the association record
154165
can be updated to replace its parent model (by replacing the foreign key)
155-
1. Currently PaperTrail only supports a single `version_associations` table.
166+
1. Currently PaperTrail-AssociationTracking only supports a single `version_associations` table.
156167
Therefore, you can only use a single table to store the versions for
157168
all related models. Sorry for those who use multiple version tables.
158-
1. PaperTrail relies on the callbacks on the association model (and the :through
169+
1. PaperTrail-AssociationTracking relies on the callbacks on the association model (and the :through
159170
association model for Has-Many-Through associations) to record the versions
160171
and the relationship between the versions. If the association is changed
161172
without invoking the callbacks, Reification won't work. Below are some
162173
examples:
163174

164-
Given these models:
175+
Given these models:
165176

166-
```ruby
167-
class Book < ActiveRecord::Base
168-
has_many :authorships, dependent: :destroy
169-
has_many :authors, through: :authorships, source: :person
170-
has_paper_trail
171-
end
177+
```ruby
178+
class Book < ActiveRecord::Base
179+
has_many :authorships, dependent: :destroy
180+
has_many :authors, through: :authorships, source: :person
181+
has_paper_trail
182+
end
172183

173-
class Authorship < ActiveRecord::Base
174-
belongs_to :book
175-
belongs_to :person
176-
has_paper_trail # NOTE
177-
end
184+
class Authorship < ActiveRecord::Base
185+
belongs_to :book
186+
belongs_to :person
187+
has_paper_trail # NOTE
188+
end
178189

179-
class Person < ActiveRecord::Base
180-
has_many :authorships, dependent: :destroy
181-
has_many :books, through: :authorships
182-
has_paper_trail
183-
end
184-
```
190+
class Person < ActiveRecord::Base
191+
has_many :authorships, dependent: :destroy
192+
has_many :books, through: :authorships
193+
has_paper_trail
194+
end
195+
```
185196

186-
Then each of the following will store authorship versions:
197+
Then each of the following will store authorship versions:
187198

188-
```ruby
189-
@book.authors << @dostoyevsky
190-
@book.authors.create name: 'Tolstoy'
191-
@book.authorships.last.destroy
192-
@book.authorships.clear
193-
@book.author_ids = [@solzhenistyn.id, @dostoyevsky.id]
194-
```
199+
```ruby
200+
@book.authors << @dostoyevsky
201+
@book.authors.create name: 'Tolstoy'
202+
@book.authorships.last.destroy
203+
@book.authorships.clear
204+
@book.author_ids = [@solzhenistyn.id, @dostoyevsky.id]
205+
```
195206

196-
But none of these will:
207+
But none of these will:
197208

198-
```ruby
199-
@book.authors.delete @tolstoy
200-
@book.author_ids = []
201-
@book.authors = []
202-
```
209+
```ruby
210+
@book.authors.delete @tolstoy
211+
@book.author_ids = []
212+
@book.authors = []
213+
```
203214

204-
Having said that, you can apparently get all these working (I haven't tested it
205-
myself) with this patch:
215+
Having said that, you can apparently get all these working (I haven't tested it
216+
myself) with this patch:
206217
207-
```ruby
208-
# In config/initializers/active_record_patch.rb
209-
module ActiveRecord
210-
# = Active Record Has Many Through Association
211-
module Associations
212-
class HasManyThroughAssociation < HasManyAssociation #:nodoc:
213-
alias_method :original_delete_records, :delete_records
218+
```ruby
219+
# config/initializers/active_record_patch.rb
214220
221+
class HasManyThroughAssociationPatch
215222
def delete_records(records, method)
216223
method ||= :destroy
217-
original_delete_records(records, method)
224+
super
218225
end
219226
end
220-
end
221-
end
222-
```
223-
224-
See [issue 113](https://github.com/paper-trail-gem/paper_trail/issues/113) for a discussion about this.
225227
228+
ActiveRecord::Associations::HasManyThroughAssociation.prepend(HasManyThroughAssociationPatch)
229+
```
226230
227-
### ActiveRecord Single Table Inheritance (STI)
231+
See [PT Issue #113](https://github.com/paper-trail-gem/paper_trail/issues/113) for a discussion about this.
228232
229-
At this time during `reify` any STI `has_one` associations will raise a `PaperTrail::Reifiers::HasOne::FoundMoreThanOne` error. See https://github.com/airblade/paper_trail/issues/594
230233
231-
Something to note though, is while the PaperTrail gem supports [Single Table Inheritance](http://api.rubyonrails.org/classes/ActiveRecord/Base.html#class-ActiveRecord::Base-label-Single+table+inheritance), I dont recommend STI ever. Your better off rolling your own solution rather than using STI.
234+
### Regarding ActiveRecord Single Table Inheritance (STI)
232235
236+
At this time during `reify` any STI `has_one` associations will raise a `PaperTrail::Reifiers::HasOne::FoundMoreThanOne` error. See [PT Issue #594](https://github.com/airblade/paper_trail/issues/594)
233237
234-
## Articles
238+
Something to note though, is while the PaperTrail gem supports [Single Table Inheritance](http://api.rubyonrails.org/classes/ActiveRecord/Base.html#class-ActiveRecord::Base-label-Single+table+inheritance), I do NOT recommend STI ever. Your better off rolling your own solution rather than using STI.
235239
236-
* [Example Title](the_article_url),
237-
[Example Author](the_author_url), 2018-05-18
240+
# Contributing
238241
239-
## Contributing
242+
See the paper_trail [contribution guidelines](https://github.com/paper-trail-gem/paper_trail/blob/master/.github/CONTRIBUTING.md)
240243
241-
See our [contribution guidelines](https://github.com/paper-trail-gem/paper_trail/blob/master/.github/CONTRIBUTING.md)
244+
# Credits
242245
243-
## Credits
246+
Plugin authored by [Weston Ganger](https://github.com/westonganger) & Jared Beck
244247
245-
Maintained by [Weston Ganger](https://github.com/westonganger)
248+
Maintained by [Weston Ganger](https://github.com/westonganger) & [Jared Beck](https://github.com/jaredbeck)
246249
247-
Associations code originally authored by Ben Atkins, Jared Beck, & more
250+
Associations code originally contributed by Ben Atkins, Jared Beck, Andy Stewart & more
248251
249252
[1]: https://api.travis-ci.org/westonganger/paper_trail-association_tracking.svg?branch=master
250253
[2]: https://travis-ci.org/westonganger/paper_trail-association_tracking

0 commit comments

Comments
 (0)