paper_trail_diff 0.14.0 → 0.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +501 -0
- data/QUICKSTART.md +21 -4
- data/README.md +59 -56
- data/docs/architecture.md +32 -11
- data/docs/performance.md +125 -391
- data/docs/reference.md +470 -117
- data/docs/testing.md +83 -7
- data/lib/paper_trail_diff/activity_boundary.rb +83 -26
- data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
- data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
- data/lib/paper_trail_diff/activity_event.rb +41 -10
- data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
- data/lib/paper_trail_diff/activity_history.rb +34 -9
- data/lib/paper_trail_diff/activity_range.rb +18 -3
- data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
- data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
- data/lib/paper_trail_diff/activity_target_candidate_loader.rb +5 -5
- data/lib/paper_trail_diff/activity_timeline_builder.rb +272 -111
- data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
- data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
- data/lib/paper_trail_diff/activity_version_collector.rb +7 -5
- data/lib/paper_trail_diff/activity_view.rb +69 -0
- data/lib/paper_trail_diff/analysis.rb +37 -6
- data/lib/paper_trail_diff/analysis_batch.rb +25 -31
- data/lib/paper_trail_diff/approximate_paths.rb +48 -0
- data/lib/paper_trail_diff/association_activity_edge.rb +6 -6
- data/lib/paper_trail_diff/association_discovery.rb +9 -1
- data/lib/paper_trail_diff/association_key.rb +56 -0
- data/lib/paper_trail_diff/association_traversal.rb +13 -4
- data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
- data/lib/paper_trail_diff/batch_preload.rb +53 -0
- data/lib/paper_trail_diff/batched_root_analyzer.rb +18 -14
- data/lib/paper_trail_diff/batched_root_versions.rb +38 -14
- data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
- data/lib/paper_trail_diff/change_row.rb +133 -0
- data/lib/paper_trail_diff/collection_comparator.rb +5 -32
- data/lib/paper_trail_diff/configuration.rb +35 -12
- data/lib/paper_trail_diff/deleted_analysis_batch.rb +23 -19
- data/lib/paper_trail_diff/deleted_root_filter.rb +101 -0
- data/lib/paper_trail_diff/deprecation.rb +61 -0
- data/lib/paper_trail_diff/diagnostics.rb +86 -99
- data/lib/paper_trail_diff/endpoint.rb +26 -3
- data/lib/paper_trail_diff/errors.rb +3 -1
- data/lib/paper_trail_diff/fallback_paths.rb +38 -0
- data/lib/paper_trail_diff/historical_association_reifier.rb +2 -4
- data/lib/paper_trail_diff/historical_filter.rb +19 -10
- data/lib/paper_trail_diff/historical_snapshot_store.rb +57 -67
- data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -35
- data/lib/paper_trail_diff/nested_comparator.rb +19 -18
- data/lib/paper_trail_diff/paper_trail_adapter.rb +198 -166
- data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +13 -1
- data/lib/paper_trail_diff/prepared_activity_index.rb +17 -13
- data/lib/paper_trail_diff/prepared_edge_loader.rb +2 -1
- data/lib/paper_trail_diff/prepared_history.rb +15 -1
- data/lib/paper_trail_diff/prepared_history_loader.rb +2 -3
- data/lib/paper_trail_diff/prepared_record_index.rb +42 -7
- data/lib/paper_trail_diff/read_snapshot.rb +77 -0
- data/lib/paper_trail_diff/root_version_selection.rb +4 -2
- data/lib/paper_trail_diff/scope_condition.rb +157 -32
- data/lib/paper_trail_diff/scope_ranking.rb +23 -14
- data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +29 -11
- data/lib/paper_trail_diff/scoped_root_selection.rb +29 -16
- data/lib/paper_trail_diff/snapshot.rb +16 -1
- data/lib/paper_trail_diff/support.rb +29 -2
- data/lib/paper_trail_diff/time_range.rb +39 -16
- data/lib/paper_trail_diff/timeline_builder.rb +13 -7
- data/lib/paper_trail_diff/timeline_range.rb +9 -1
- data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
- data/lib/paper_trail_diff/transaction_cut.rb +240 -0
- data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
- data/lib/paper_trail_diff/version.rb +1 -1
- data/lib/paper_trail_diff/version_boundary.rb +41 -10
- data/lib/paper_trail_diff/version_query.rb +34 -10
- data/lib/paper_trail_diff/version_scope_filter.rb +9 -10
- data/lib/paper_trail_diff/version_sequence_diagnostics.rb +35 -17
- data/lib/paper_trail_diff/version_table.rb +60 -0
- data/lib/paper_trail_diff.rb +101 -57
- data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
- data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
- data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
- data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
- data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
- data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
- data/sig/generated/paper_trail_diff/activity_range.rbs +9 -2
- data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
- data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
- data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -30
- data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
- data/sig/generated/paper_trail_diff/activity_version_collector.rbs +2 -0
- data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
- data/sig/generated/paper_trail_diff/analysis.rbs +24 -5
- data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
- data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
- data/sig/generated/paper_trail_diff/association_discovery.rbs +5 -0
- data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
- data/sig/generated/paper_trail_diff/association_traversal.rbs +4 -0
- data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
- data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -10
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -4
- data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
- data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
- data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
- data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
- data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -8
- data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +56 -0
- data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
- data/sig/generated/paper_trail_diff/diagnostics.rbs +37 -30
- data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
- data/sig/generated/paper_trail_diff/errors.rbs +3 -1
- data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
- data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
- data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +33 -28
- data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +0 -15
- data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
- data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +64 -52
- data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
- data/sig/generated/paper_trail_diff/prepared_history.rbs +10 -0
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +20 -2
- data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
- data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
- data/sig/generated/paper_trail_diff/scope_condition.rbs +81 -15
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +14 -6
- data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +14 -2
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +16 -7
- data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
- data/sig/generated/paper_trail_diff/support.rbs +15 -0
- data/sig/generated/paper_trail_diff/time_range.rbs +24 -9
- data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
- data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
- data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
- data/sig/generated/paper_trail_diff/transaction_cut.rbs +126 -0
- data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
- data/sig/generated/paper_trail_diff/version_boundary.rbs +22 -3
- data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
- data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -5
- data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +19 -9
- data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
- data/sig/generated/paper_trail_diff.rbs +29 -26
- metadata +49 -11
- data/lib/paper_trail_diff/activity_grouping.rb +0 -38
- data/lib/paper_trail_diff/batch_safety.rb +0 -63
- data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -223
- data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
- data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -30
- data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 31ad8d55dab710a7295d5c6fef92918fee436492e35ec6fa785f49de025c2994
|
|
4
|
+
data.tar.gz: 04c4f17548bcda07300bb857dc6194b698f907bb1b71db06e61dbb3037e533dd
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 6a2cbc59fa7e53d31b78b1f0d5863519e1c72063718791323b938f73668ee53ddb19f6ac5cdf4d72b656dc6ec5c154e26485994da2ac90a6141d67928668c4ed
|
|
7
|
+
data.tar.gz: 7700f7863dcd954cea284ea1564def6a1d4b2a8679dd49a01bf618cf36333b6aba8c7e83b32cc7f2c481c81701ef5127c899c8cb9ce551c6379cc608273dfc68
|
data/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,507 @@
|
|
|
3
3
|
All notable changes to this project will be documented in this file. The
|
|
4
4
|
project follows [Semantic Versioning](https://semver.org/).
|
|
5
5
|
|
|
6
|
+
## [0.16.0] - 2026-11-01
|
|
7
|
+
|
|
8
|
+
### Changed
|
|
9
|
+
|
|
10
|
+
- `include_deleted:` reads the deleted records' `destroy` versions 500
|
|
11
|
+
records per query, as `unreachable`'s test below does, instead of in one
|
|
12
|
+
query for all of them.
|
|
13
|
+
|
|
14
|
+
- The reference says what `from_snapshot` holds at the start of a window,
|
|
15
|
+
under `version_scope:`, and for a record created inside the range, and how
|
|
16
|
+
to read a record at one version from an analysis rather than by decoding
|
|
17
|
+
`version.object`, which skips the casting the gem applies.
|
|
18
|
+
|
|
19
|
+
- `analyze_scope` and `report` with `version_scope:` select a record by its
|
|
20
|
+
own versions only when the filter keeps one of them in the window. A record
|
|
21
|
+
whose versions there it all dropped was selected anyway, with an empty
|
|
22
|
+
analysis, and counted toward `limit:`. A change on a requested association
|
|
23
|
+
still selects a record, as before.
|
|
24
|
+
|
|
25
|
+
- `report` and `analyze_scope` list in `unreachable` only the deleted records
|
|
26
|
+
whose state when destroyed meets the relation's conditions, also without
|
|
27
|
+
`include_deleted:`, whenever those conditions can be read. A report on
|
|
28
|
+
`Article.where(account_id: account.id)` listed every account's deleted
|
|
29
|
+
articles there, and one on `Article.none` listed some too. A relation whose
|
|
30
|
+
conditions cannot be read, such as one with SQL text, lists every deleted
|
|
31
|
+
record of the model as before.
|
|
32
|
+
|
|
33
|
+
### Added
|
|
34
|
+
|
|
35
|
+
- `report` accepts `version_scope:`, as `analyze_scope` does, to report only
|
|
36
|
+
some changes, such as those made by people rather than by background jobs.
|
|
37
|
+
|
|
38
|
+
- `Analysis#window` is the time window an analysis covers: the `within:` or
|
|
39
|
+
`since:` range, or that range with an edge moved back to where a crossing
|
|
40
|
+
transaction began. Check steps against it rather than against the range you
|
|
41
|
+
passed, which the first step of a moved window starts before. It is `nil`
|
|
42
|
+
without a window.
|
|
43
|
+
|
|
44
|
+
- A `moved_window.paper_trail_diff` notification reports each window edge that
|
|
45
|
+
moved, with the requested and the moved window. A move far longer than a
|
|
46
|
+
transaction takes means the versions' times were changed after saving, as in
|
|
47
|
+
a test that rewrote some versions' `created_at` and not the others saved in
|
|
48
|
+
the same transaction. The reference shows how to give versions fixed times
|
|
49
|
+
in tests.
|
|
50
|
+
|
|
51
|
+
- Association scopes and `include_deleted:` relations read ranges, such as
|
|
52
|
+
`where(position: 2..)` or `where(created_at: 1.day.ago..)`, and Arel's `gt`,
|
|
53
|
+
`gteq`, `lt`, and `lteq`, on integer, integer enum, date, and datetime
|
|
54
|
+
columns. Such a scope was read through PT-AT, which needs
|
|
55
|
+
`allow_approximate: true`, and such a relation raised `ConfigurationError`
|
|
56
|
+
under `include_deleted: true`.
|
|
57
|
+
|
|
58
|
+
- `include_deleted: true` accepts `Article.none`, which keeps no deleted
|
|
59
|
+
record, instead of raising `ConfigurationError`. Authorization scopes often
|
|
60
|
+
return `none`.
|
|
61
|
+
|
|
62
|
+
### Fixed
|
|
63
|
+
|
|
64
|
+
- Batch methods with `within:` or `since:` look for transactions that cross
|
|
65
|
+
the window's edges in one statement per 500 records. 0.15.0 wrote a
|
|
66
|
+
separate lookup for each record into the statement, which SQL Server took
|
|
67
|
+
about a second to compile per 200 records, so a report on 10,800 records
|
|
68
|
+
spent nearly two minutes there. On 1.4 million versions, 0.15.0 failed for
|
|
69
|
+
10,800 records on SQL Server, whose query processor ran out of internal
|
|
70
|
+
resources, and took 13.6 and 10.2 seconds on PostgreSQL and MySQL. Those
|
|
71
|
+
edges now take about 6 seconds on SQL Server and about 1.5 on PostgreSQL
|
|
72
|
+
and MySQL.
|
|
73
|
+
|
|
74
|
+
- On PostgreSQL and MySQL (through mysql2 or trilogy), and adapters built on
|
|
75
|
+
them such as PostGIS, each call reads its history and live rows in one
|
|
76
|
+
REPEATABLE READ transaction on the database of the model and its versions.
|
|
77
|
+
A comment that
|
|
78
|
+
committed between two statements of an activity read could make it raise an
|
|
79
|
+
internal `KeyError`, and one statement could see a row that another did not.
|
|
80
|
+
A call now reflects the database as of its first statement, so a commit
|
|
81
|
+
during the call appears in the next call. Each call adds two or three
|
|
82
|
+
transaction statements on those databases. A call made inside a transaction
|
|
83
|
+
of your own keeps that transaction's isolation level. SQLite and SQL Server
|
|
84
|
+
are unchanged.
|
|
85
|
+
|
|
86
|
+
- Activity reports a change to a root's `belongs_to` key in the step of the
|
|
87
|
+
root version that made it, also when `object_changes` leaves the key out:
|
|
88
|
+
under `has_paper_trail only:` or `ignore:` that do not list it, or when
|
|
89
|
+
`update_columns`, `update_all`, or a save with versioning off wrote it. The
|
|
90
|
+
root kept its old target until a later event read the branch again, so the
|
|
91
|
+
change was credited to whoever saved that, two windows that met between
|
|
92
|
+
the two reported it in neither, and `analyze(activity: true).timeline`
|
|
93
|
+
differed from `timeline`.
|
|
94
|
+
|
|
95
|
+
- Activity reads a child or a `belongs_to` target whose key changed without a
|
|
96
|
+
version, such as a comment moved by `update_columns`, or by any save under
|
|
97
|
+
`has_paper_trail only:` or `ignore:` that leave the key out. In a past
|
|
98
|
+
window or a range that ends at a version, the record had no events: it
|
|
99
|
+
joined at an arbitrary later step, or was left out of the window's diff,
|
|
100
|
+
and a reviewer set this way kept its later renames out of activity.
|
|
101
|
+
|
|
102
|
+
- `analyze_many`, and the `deleted` analyses of `analyze_scope`, give a record
|
|
103
|
+
with nothing in the window an `activity_timeline` of `nil` unless
|
|
104
|
+
`activity: true` was passed, as `analyze` does, so its `change_rows` raises
|
|
105
|
+
`ConfigurationError` as for any other record. It was `[]`, so code that read
|
|
106
|
+
`change_rows` without asking for activity passed while nothing changed.
|
|
107
|
+
|
|
108
|
+
- An STI root that changes class names its new class in the activity
|
|
109
|
+
snapshots after the change, not its old one, and a subclass root's
|
|
110
|
+
snapshot is carried from one of its versions to the next instead of being
|
|
111
|
+
rebuilt at each one.
|
|
112
|
+
|
|
113
|
+
- Activity reports a change to a key that a child's own `belongs_to`
|
|
114
|
+
follows, such as a comment's `reviewer_id` under `comments.reviewer`, in
|
|
115
|
+
the step of the child's update. The child kept its old target until its
|
|
116
|
+
next edit, or a root version, read the branch again, so the change showed
|
|
117
|
+
up in a later step, credited to whoever saved that, and a window that
|
|
118
|
+
held only the change reported nothing.
|
|
119
|
+
|
|
120
|
+
- Activity removes a `has_many :through` member when its join record moves
|
|
121
|
+
to another owner or points at another record, also when a path below the
|
|
122
|
+
through reads that join model again, as `contributors.authorships` does.
|
|
123
|
+
The update changed only the copy under that path, so the through kept the
|
|
124
|
+
member until another event read the branch again.
|
|
125
|
+
|
|
126
|
+
- A HABTM member created in a checkpoint's transaction appears in activity
|
|
127
|
+
from its creation on, as in 0.14.0. Since 0.15.0, which counts such a
|
|
128
|
+
member at the checkpoint, it appeared in every step back to the previous
|
|
129
|
+
root version, before it existed and before members attached earlier. A
|
|
130
|
+
range that ends at the checkpoint still ends with it, as `compare` does.
|
|
131
|
+
|
|
132
|
+
### Development
|
|
133
|
+
|
|
134
|
+
- `spec/oracle/replay_differential_spec.rb` replays generated histories
|
|
135
|
+
with activity's incremental snapshots and with a full snapshot at every
|
|
136
|
+
event, under `has_paper_trail only:` and `ignore:` and with keys written
|
|
137
|
+
without a version, and fails on any difference. It found the first two
|
|
138
|
+
bugs above.
|
|
139
|
+
|
|
140
|
+
- The through oracle renames a team at most once per transaction. A second
|
|
141
|
+
rename made it expect a version to read the state before its transaction,
|
|
142
|
+
which made `ORACLE_SEEDS=40..49` fail on seed 45 without a bug. The scoped
|
|
143
|
+
membership oracle covers range scopes.
|
|
144
|
+
|
|
145
|
+
- Two oracle generators compare rebuilt history with plain Active Record:
|
|
146
|
+
`spec/oracle/through_history_spec.rb` for every kind of `has_many :through`,
|
|
147
|
+
and `spec/oracle/habtm_history_spec.rb` for HABTM membership between
|
|
148
|
+
checkpoints. They found the three activity bugs above.
|
|
149
|
+
|
|
150
|
+
- Specs check that a range orders versions by time when their ids run the
|
|
151
|
+
other way, and that an STI subclass's selection names only its own
|
|
152
|
+
destroyed rows. A stub of the versions association these specs relied on
|
|
153
|
+
stopped reaching the gem when it began reading versions from the version
|
|
154
|
+
class, which left six mutations alive in a full mutation run.
|
|
155
|
+
|
|
156
|
+
## [0.15.0] - 2026-10-31
|
|
157
|
+
|
|
158
|
+
### Breaking changes
|
|
159
|
+
|
|
160
|
+
- A `within:` or `since:` window, and a range that starts at a version, can
|
|
161
|
+
begin earlier than asked: an edge inside a transaction moves back to where
|
|
162
|
+
the transaction began, as the two entries under Fixed describe. The first
|
|
163
|
+
step of such a range has a `from_boundary` before the time or version you
|
|
164
|
+
passed, so code that drops steps outside the range it asked for loses that
|
|
165
|
+
step. (This entry was added after release; 0.15.0 listed the change only
|
|
166
|
+
under Fixed.)
|
|
167
|
+
|
|
168
|
+
- An association whose model keeps its versions, or its PT-AT version
|
|
169
|
+
associations, in different tables than its owner's raises
|
|
170
|
+
`UnsupportedAssociationError` in every method, and `association_paths`
|
|
171
|
+
leaves it out. History read through it was wrong: PT-AT records a child's
|
|
172
|
+
membership with the child's versions but reads it from the owner's tables,
|
|
173
|
+
so a child that moved to another owner was never reported as removed, and a
|
|
174
|
+
root with its own version table raised `ActiveRecord::StatementInvalid`.
|
|
175
|
+
|
|
176
|
+
- An association keyed on a column other than a primary key
|
|
177
|
+
(`primary_key: :legacy_id`), or a `has_many :through` with such a part,
|
|
178
|
+
raises `UnsupportedAssociationError` up front in every method, and
|
|
179
|
+
`association_paths` leaves it out. PT-AT records which record a child
|
|
180
|
+
pointed at by that record's ID, and history matched children by ID, so an
|
|
181
|
+
article's history showed another article's comments, and a comment's past
|
|
182
|
+
article was the wrong one. Comparisons against the current record were
|
|
183
|
+
right, so the same range disagreed with itself.
|
|
184
|
+
- An association path history cannot read, such as one with a scope written
|
|
185
|
+
as SQL text, a scope that takes the owner, or a condition on a string
|
|
186
|
+
column on MySQL or SQL Server, raises `UnsupportedAssociationError` in every
|
|
187
|
+
method that reads history, unless you pass the new `allow_approximate: true`.
|
|
188
|
+
The gem reads such a path with PT-AT, which rebuilds an association from its
|
|
189
|
+
current members and never checks the scope against them: a record that
|
|
190
|
+
entered the scope since was reported as a member it was not, so a comment
|
|
191
|
+
moved into `-> { where("position > 2") }` showed as changed rather than
|
|
192
|
+
added. Single-record methods did this without warning, and batch methods
|
|
193
|
+
described it only as costly.
|
|
194
|
+
- `include_deleted: true` keeps only the deleted records that met the
|
|
195
|
+
relation's conditions when they were destroyed, in both `deleted` and
|
|
196
|
+
`unreachable`. It returned every deleted record of the model that changed in
|
|
197
|
+
the window, so a report on one account's articles included other accounts'
|
|
198
|
+
deleted articles with their contents. The relation's conditions must be
|
|
199
|
+
plain conditions on the model's own columns; a join or SQL text raises
|
|
200
|
+
`ConfigurationError`.
|
|
201
|
+
|
|
202
|
+
### Added
|
|
203
|
+
|
|
204
|
+
- `diagnose` reports every reason `compare` would refuse the same request as
|
|
205
|
+
an error, with `compare`'s message, so `ok?` is false whenever `compare`
|
|
206
|
+
would refuse. It said `ok?` for a path `compare` reads only approximately,
|
|
207
|
+
such as a scope written as SQL text, raised on an unknown or unsupported
|
|
208
|
+
association instead of reporting it, and checked only the join model a
|
|
209
|
+
`has_many :through` goes through first, not every model it reads. It
|
|
210
|
+
takes `allow_approximate:`, and with `true` reports such a path as an
|
|
211
|
+
`:approximate_association` warning. The new error codes are
|
|
212
|
+
`:unknown_association`, `:unsupported_association`, and
|
|
213
|
+
`:approximate_association`; an unversioned target's message now matches
|
|
214
|
+
`compare`'s.
|
|
215
|
+
|
|
216
|
+
- `diagnose` takes the current record as either endpoint, as `compare` does,
|
|
217
|
+
so `compare(version, record)` can be checked before it runs. Its version
|
|
218
|
+
checks then run from the version to the latest one. An endpoint that is
|
|
219
|
+
neither a version nor a saved record raises `InvalidEndpointError` naming
|
|
220
|
+
that, rather than `VersionMismatchError`.
|
|
221
|
+
|
|
222
|
+
- Activity steps list the events whose changes they show as `step.sources`,
|
|
223
|
+
oldest first. A step from `group: :transaction` lists every event in the
|
|
224
|
+
transaction, each with its own author, record, and version ID, where
|
|
225
|
+
`source_boundary` names only the first. `to_h(metadata: true)` adds a
|
|
226
|
+
`sources` list.
|
|
227
|
+
- `recorded_changes: true` on `activity_timeline`, on `analyze`, `analyze_many`,
|
|
228
|
+
and `analyze_scope` with `activity: true`, and on `report` gives each
|
|
229
|
+
boundary the changes its version recorded, as `recorded_changes(version)`
|
|
230
|
+
returns them. The versions are already loaded, so it adds no queries, and it
|
|
231
|
+
replaces the reference recipe that loaded every step's version again.
|
|
232
|
+
Without the option, `boundary.recorded_changes` raises `ConfigurationError`
|
|
233
|
+
rather than returning `nil`. Names in `ignore:` or `ignore: { all: }` are
|
|
234
|
+
left out, and so are names on the root path, `"$"`, for the root's own
|
|
235
|
+
versions. Names on an association path are not, because a child's version
|
|
236
|
+
does not say which path reached it.
|
|
237
|
+
- `change_rows` on an activity step, on an `Analysis` built with
|
|
238
|
+
`activity: true`, and on a `report` or `analyze_scope` result flattens
|
|
239
|
+
activity into `ChangeRow` objects: one per edited field, and one per record
|
|
240
|
+
that appeared or disappeared followed by its fields. Each names its record,
|
|
241
|
+
association path, and source version, and `to_h` gives a flat hash. It
|
|
242
|
+
replaces the README recipe for turning a report into rows, which had no rows
|
|
243
|
+
for whole records, so a record added or removed with only blank fields left
|
|
244
|
+
no trace.
|
|
245
|
+
|
|
246
|
+
- `associations:` takes what `includes` takes: a single name
|
|
247
|
+
(`associations: :comments`) or hashes of names to what to include below them
|
|
248
|
+
(`associations: [:author, { comments: :replies }]`), as well as the arrays of
|
|
249
|
+
names and dotted paths it took before.
|
|
250
|
+
|
|
251
|
+
- `nested_changes` compares two top-level arrays, as a `json` column can hold,
|
|
252
|
+
and reports one `ArrayChange` at the empty path, `[]`. It returned `{}`,
|
|
253
|
+
although arrays nested in an object were compared.
|
|
254
|
+
|
|
255
|
+
### Changed
|
|
256
|
+
|
|
257
|
+
- The reference describes how PT-AT records HABTM membership and how the gem
|
|
258
|
+
credits it. A change made between two root versions is credited to the
|
|
259
|
+
step after the earlier one, so a checkpoint's capture is credited to whoever
|
|
260
|
+
saved the version before it; a checkpoint just before the change as well
|
|
261
|
+
credits it to its author. Only the first version an instance saves after
|
|
262
|
+
changing a HABTM is right; PT-AT never forgets the instance's changes, not
|
|
263
|
+
even on `reload`. A later save from it records the old membership, and the
|
|
264
|
+
gem reports members removed and added again that never left.
|
|
265
|
+
|
|
266
|
+
- The performance guide describes current behavior instead of logging each
|
|
267
|
+
past change: what the batch methods cost, what still grows with a report,
|
|
268
|
+
the version indexes, what costs a query per record, historical filters,
|
|
269
|
+
large reports, and how to measure. Its measurements were taken again. The
|
|
270
|
+
earlier ones remain in `benchmark/results/` and in the changelog.
|
|
271
|
+
|
|
272
|
+
- `historical_filter:` reads the history of the relation's records only, and
|
|
273
|
+
of deleted records, which a relation cannot test. It read every record of
|
|
274
|
+
the model that changed in the window, so a report on one account's articles
|
|
275
|
+
raised `BatchLimitExceededError` when another account had more matching
|
|
276
|
+
articles than `limit:`, and spent `max_filter_versions:` on their versions.
|
|
277
|
+
Matching deleted records no longer count toward `limit:` unless
|
|
278
|
+
`include_deleted: true` is given, as without a filter.
|
|
279
|
+
|
|
280
|
+
- The reference says how a record created without a version, such as one
|
|
281
|
+
imported with `insert_all`, and history pruned with `has_paper_trail
|
|
282
|
+
limit:` read.
|
|
283
|
+
|
|
284
|
+
- `IncompleteTimeRangeError` no longer advises the deprecated
|
|
285
|
+
`close_on: :current`. The quickstart and performance guide no longer say
|
|
286
|
+
that `has_many :through` or limited associations need the opt-ins, and the
|
|
287
|
+
reference says that `association_paths` lists paths that need
|
|
288
|
+
`allow_approximate: true`.
|
|
289
|
+
|
|
290
|
+
- The quickstart sets PaperTrail's `yaml_column_permitted_classes`. In a new
|
|
291
|
+
Rails 8.1 app, versions hold timestamps as `ActiveSupport::TimeWithZone`,
|
|
292
|
+
and the quickstart's first `reify` raised `Psych::DisallowedClass` without
|
|
293
|
+
it. Its documentation spec now reads a version in that form.
|
|
294
|
+
|
|
295
|
+
- The README and architecture guide recommend a second version index,
|
|
296
|
+
`(item_type, created_at, item_id)`. Batch methods with `since:` or
|
|
297
|
+
`within:` find changed records by type and time, which the one index they
|
|
298
|
+
recommended cannot narrow, so each report read every version of the model:
|
|
299
|
+
about 230 ms instead of 2 ms on PostgreSQL with 5 million versions.
|
|
300
|
+
- The gemspec requires Active Record 7.1 to 8.1. CI tests 7.2 through 8.1,
|
|
301
|
+
and the suite passes on 7.1. It named only PaperTrail, so Bundler could
|
|
302
|
+
install the gem with Active Record 6.1 or 7.0, whose relations and Arel
|
|
303
|
+
nodes the gem reads differently.
|
|
304
|
+
- `close_on:` is deprecated and warns through the new
|
|
305
|
+
`PaperTrailDiff.deprecator`. It has had no effect since a window began
|
|
306
|
+
closing on the current record by default; remove it. In a Rails app,
|
|
307
|
+
register the deprecator with
|
|
308
|
+
`Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator`.
|
|
309
|
+
- `allow_expensive:` is deprecated and has no effect. It refused exactly the
|
|
310
|
+
paths `allow_approximate:` refuses, so batch methods needed both or
|
|
311
|
+
neither; `allow_approximate: true` alone now accepts such a path in every
|
|
312
|
+
method, and `UnsupportedBatchPathError` is no longer raised. Batch methods
|
|
313
|
+
refuse such a path before their first query, as before, now with
|
|
314
|
+
`UnsupportedAssociationError`.
|
|
315
|
+
- `reload_live_endpoints:` is deprecated and warns. It still works until it
|
|
316
|
+
is removed. Skipping the reload saves a query for the records and one per
|
|
317
|
+
association level in each call, 2 for 500 articles with their comments,
|
|
318
|
+
and reads values from objects that may be stale; it also needs every
|
|
319
|
+
requested association loaded, and reads limited ones again anyway. It was
|
|
320
|
+
on `compare`, `compare_many`, and `activity_timeline` only. Remove it.
|
|
321
|
+
|
|
322
|
+
### Fixed
|
|
323
|
+
|
|
324
|
+
- A HABTM member created in the same transaction as the checkpoint that
|
|
325
|
+
records it is a member at that checkpoint, as a member attached there
|
|
326
|
+
already was. It was left out, because it had no state before the
|
|
327
|
+
transaction, so the checkpoint missed it and a comparison from the
|
|
328
|
+
checkpoint to now reported it added.
|
|
329
|
+
|
|
330
|
+
- `association_paths` leaves out an association whose target, or a model its
|
|
331
|
+
`has_many :through` goes through, has no `has_paper_trail`, such as the
|
|
332
|
+
`file_attachment` and `file_blob` that `has_one_attached` defines. Every
|
|
333
|
+
request that reads history refused them with `UnversionedAssociationError`,
|
|
334
|
+
so a settings screen built from the list offered paths that always failed.
|
|
335
|
+
|
|
336
|
+
- `diagnose` reports `:tied_version_timestamps`, and `compare` emits
|
|
337
|
+
`ambiguous_association_boundary.paper_trail_diff`, only when the request can
|
|
338
|
+
read a path with PT-AT: one history reads only approximately, a composite
|
|
339
|
+
foreign key, or a polymorphic `belongs_to`. PT-AT places association changes
|
|
340
|
+
by timestamp alone. For every other path, since 0.14.0, versions that share a
|
|
341
|
+
timestamp are ordered by ID, so a change between them is reported, yet both
|
|
342
|
+
warned that it could not be detected. A request refused for a path PT-AT
|
|
343
|
+
would read now raises before the notification.
|
|
344
|
+
|
|
345
|
+
- `timeline`, `activity_timeline`, and `analyze` read every version of a
|
|
346
|
+
model whose versions association has a scope
|
|
347
|
+
(`has_paper_trail versions: { scope: }`), as the other methods already did.
|
|
348
|
+
They read only the versions the scope kept, so a change saved in a version
|
|
349
|
+
it left out was credited to the next one kept: with a bot's edits hidden,
|
|
350
|
+
an editor's step showed the bot's later edit too, and the same record and
|
|
351
|
+
window gave different steps in `analyze` and `analyze_many`. A version the
|
|
352
|
+
scope leaves out is also accepted as an endpoint. To report only some
|
|
353
|
+
changes, pass `version_scope:`.
|
|
354
|
+
|
|
355
|
+
- Activity steps leave out the versions a record saved while it was outside
|
|
356
|
+
the root's tree. A comment edited on another article, then moved to this
|
|
357
|
+
one, brought that edit into the article's timeline as a step, and a
|
|
358
|
+
transaction group's `sources` listed it. Saved together with a comment added
|
|
359
|
+
to the article, the edit took the credit for the addition. The same went for
|
|
360
|
+
a comment edited after it moved away or left a scope, and for an author
|
|
361
|
+
renamed after the article changed authors. A version now counts when its
|
|
362
|
+
record is in the tree before or after its transaction. The versions of a
|
|
363
|
+
`has_many :through`'s join rows are all still kept.
|
|
364
|
+
|
|
365
|
+
- `timeline`, `activity_timeline`, `analyze`, and `analyze_many` raise
|
|
366
|
+
`InvalidEndpointError` naming what they were given when it is not a record
|
|
367
|
+
of a versioned model, such as `nil`, a model class, a relation, or a
|
|
368
|
+
version. They raised a bare `NoMethodError`, or said to provide `from` and
|
|
369
|
+
`to`. `report` names `since` when it is `nil` or a range.
|
|
370
|
+
|
|
371
|
+
- A scope ordered by a datetime, such as
|
|
372
|
+
`-> { order(created_at: :desc, id: :desc).limit(3) }`, is read from history
|
|
373
|
+
under Rails' default time-zone-aware attributes. Rails wraps those
|
|
374
|
+
attributes' types, which hid the datetime, so every method raised
|
|
375
|
+
`UnsupportedAssociationError` for the documented recipe.
|
|
376
|
+
|
|
377
|
+
- A `Date` bound of `within:` or `since:` is a whole day in `Time.zone`, and
|
|
378
|
+
a string a time in `Time.zone`, or in UTC without one. They were read in
|
|
379
|
+
the server's own zone, so the same window covered different hours on
|
|
380
|
+
different servers, and a same-day `Date..Date` window covered one instant
|
|
381
|
+
and found nothing.
|
|
382
|
+
|
|
383
|
+
- A `has_many :through` whose join model is not versioned raises
|
|
384
|
+
`UnversionedAssociationError` naming the join model when its history is
|
|
385
|
+
read, and `diagnose` reports it as an error, so `ok?` is false. A
|
|
386
|
+
comparison raised a bare `KeyError` while `diagnose` reported only a
|
|
387
|
+
warning.
|
|
388
|
+
|
|
389
|
+
- `reload_live_endpoints: false` reads an association with a `limit` or
|
|
390
|
+
`offset`, directly or in a part it goes through, or a scope that takes the
|
|
391
|
+
owner, again for each record. Active Record's `preload` applies the limit across all the records
|
|
392
|
+
it loads, so with three articles preloaded, two kept one comment each and
|
|
393
|
+
the third none, and their unchanged comments were reported as removed.
|
|
394
|
+
|
|
395
|
+
- A root and its associations that share one version table other than
|
|
396
|
+
PaperTrail's `versions` can be compared. Association lookups joined PT-AT's
|
|
397
|
+
version associations to the `versions` table whatever table the versions
|
|
398
|
+
were in, so every method raised `ActiveRecord::StatementInvalid`.
|
|
399
|
+
|
|
400
|
+
- A `within:` or `since:` window whose edge falls inside a transaction that
|
|
401
|
+
saved a version of the root record reports the whole transaction in the
|
|
402
|
+
later window. A window starting between a comment edit and the `touch: true`
|
|
403
|
+
article version saved with it showed the edit at the article's next change,
|
|
404
|
+
credited to that change's author, and the window ending there left it out;
|
|
405
|
+
when the article saved first, its version was in one window and the comment
|
|
406
|
+
edit in the other. Each root's edges move back to the transaction's start,
|
|
407
|
+
read in a fixed number of queries per 200 records.
|
|
408
|
+
|
|
409
|
+
- `activity_timeline`, and `analyze` with `activity: true`, no longer report a
|
|
410
|
+
child version saved in the same transaction as the root version that ends
|
|
411
|
+
the range. A `touch: true` parent version is saved this way after every
|
|
412
|
+
child save. PT-AT rebuilds the parent's associations at that version as they
|
|
413
|
+
were before the transaction, so the child's step was always empty and its
|
|
414
|
+
change was reported nowhere. The range now ends before that transaction, as
|
|
415
|
+
`compare` and `timeline` already did. End at a later version or at the
|
|
416
|
+
current record to include the change, with `group: :transaction` to credit it
|
|
417
|
+
to the child's version.
|
|
418
|
+
- A range that starts at a version now starts before that version's
|
|
419
|
+
transaction, as one that ends there already ended. A child version saved
|
|
420
|
+
earlier in the same transaction, such as the update behind a `touch: true`
|
|
421
|
+
parent version, was read after its change, so `compare`, `analyze`,
|
|
422
|
+
`timeline`, and `activity_timeline` from that version left the change out.
|
|
423
|
+
It was also missing from the range ending there, so a history split at that
|
|
424
|
+
version reported it nowhere. It is now inside the range that starts there.
|
|
425
|
+
- A past `within:` window in `activity_timeline`, and in `analyze`,
|
|
426
|
+
`analyze_many`, `analyze_scope`, and `report` with `activity: true`, no
|
|
427
|
+
longer includes association changes made after it. When the root had no
|
|
428
|
+
version after the window, the window closed on current state, so a comment
|
|
429
|
+
edited in August appeared in a July window, in its last step, `to_snapshot`,
|
|
430
|
+
and `diff`; with a later root version the same window was right. It now
|
|
431
|
+
closes on current state only when nothing on a requested path was recorded
|
|
432
|
+
after it. The reasoning in 0.8.0, that nothing had been recorded since,
|
|
433
|
+
checked only the root's own versions. `timeline`, and `analyze` without
|
|
434
|
+
`activity:`, still run their last step to the root's next version or the
|
|
435
|
+
current record; the reference now says so.
|
|
436
|
+
- Association scopes read from history now cover `IS NULL` and `IS NOT NULL`
|
|
437
|
+
on a column of any type, such as a soft-delete scope's
|
|
438
|
+
`where(deleted_at: nil)`, and `NOT` with SQL's rules for NULL, such as
|
|
439
|
+
`where.not(position: [1, nil])`. These were read with PT-AT before, so a
|
|
440
|
+
record restored from a soft delete showed as changed rather than added, and
|
|
441
|
+
batch methods refused them without `allow_expensive: true`. A condition on a
|
|
442
|
+
PostgreSQL `citext` column, which compares without regard to case, is no
|
|
443
|
+
longer read as exact text.
|
|
444
|
+
- A `historical_filter:` hash casts its values, and the recorded ones, to each
|
|
445
|
+
attribute's type before comparing them, as `where` does. An enum given as a
|
|
446
|
+
symbol (`{ status: :published }`), and a date or time read from a `json` or
|
|
447
|
+
`jsonb` version column, which PaperTrail returns as a string, never matched,
|
|
448
|
+
so the report silently selected nothing.
|
|
449
|
+
- Versions from two version tables saved in the same instant raise
|
|
450
|
+
`AmbiguousVersionOrderError`, as the reference promises, instead of being
|
|
451
|
+
ordered by their ids. Each table counts its ids separately, so their order
|
|
452
|
+
said nothing about which change came first, and an activity timeline built
|
|
453
|
+
from them could credit a change to the wrong step.
|
|
454
|
+
- `compare_many`, `analyze_many`, `analyze_scope`, and `report` load a
|
|
455
|
+
`has_one` of every current record in one query again, as before 0.14.0.
|
|
456
|
+
0.14.0 meant to load only a `has_one` with a declared limit or offset per
|
|
457
|
+
record, but checked the association's scope, to which Active Record adds
|
|
458
|
+
`limit(1)` for every `has_one`, so every `has_one` cost one query per
|
|
459
|
+
record.
|
|
460
|
+
- `report`, `analyze_scope`, and `analyze_many` with `activity: true` no
|
|
461
|
+
longer read a root's current row once more for activity through a
|
|
462
|
+
`has_many :through` after its last version. The batch has already loaded
|
|
463
|
+
it, so the query count no longer grows with the number of roots.
|
|
464
|
+
- A snapshot's collections list their records by type, then ID, as the
|
|
465
|
+
reference says, wherever the snapshot was read from. Snapshots rebuilt from
|
|
466
|
+
history or carried through an activity timeline listed them in the order
|
|
467
|
+
they were found, and a ranked association in its query's order, so `to_h` of
|
|
468
|
+
the same state differed between methods. Diffs were already ordered.
|
|
469
|
+
- With a `json` or `jsonb` `object` column, an activity step no longer
|
|
470
|
+
reports an unchanged timestamp as changed. PaperTrail returns such a
|
|
471
|
+
column's times as strings, and a step after a child's update carried them
|
|
472
|
+
into the snapshot as they were, so the next step that read the child again
|
|
473
|
+
reported `created_at` changing from a string to the same time. Activity now
|
|
474
|
+
casts them as it does every other recorded state. The specs had covered the
|
|
475
|
+
JSON serializer on a text column only, which PaperTrail casts.
|
|
476
|
+
|
|
477
|
+
### Development
|
|
478
|
+
|
|
479
|
+
- A new oracle suite, `rake spec_oracle`, checks rebuilt history against the
|
|
480
|
+
truth rather than against other gem methods. It makes seeded random edits to
|
|
481
|
+
an article graph one transaction at a time, records the live state after
|
|
482
|
+
each, and compares every endpoint, timeline step, activity step, window, and
|
|
483
|
+
batch result with those states. It also checks that two windows meeting
|
|
484
|
+
between transactions or inside one report each step once, scoped membership
|
|
485
|
+
against Active Record, and a tree of one model whose children have
|
|
486
|
+
encrypted, serialized, enum, custom-type, decimal, and JSON attributes.
|
|
487
|
+
`rake spec` runs it, so CI runs it on every database. `ORACLE_SEEDS` and
|
|
488
|
+
`ORACLE_STEPS` widen a run. See `docs/testing.md`.
|
|
489
|
+
- `PTD_PROBE_ALLOW_APPROXIMATE=1` makes the reconstruction probe pass
|
|
490
|
+
`allow_approximate: true`, so its PT-AT-read scenario runs rather than
|
|
491
|
+
raising, and neither benchmark passes the deprecated `close_on:` any more.
|
|
492
|
+
- On SQL Server the association specs keep their versions 5 ms apart. Specs
|
|
493
|
+
that compare the gem with PT-AT failed at random there: PT-AT compares
|
|
494
|
+
version times through SQL text, which the SQL Server adapter writes as
|
|
495
|
+
`datetime` values up to 1/300 s off, and after the host clock stepped back
|
|
496
|
+
the test clock packed versions microseconds apart until it caught up.
|
|
497
|
+
- The reporting benchmark loads the monotonic test clock, so its results no
|
|
498
|
+
longer depend on the host clock. A clock that stepped backwards, as WSL2's
|
|
499
|
+
does, could date a root's destroy before its last update, and
|
|
500
|
+
`deleted_roots` then raised `IncompleteTimeRangeError`. The seeded history
|
|
501
|
+
and query counts are unchanged. Allocations rise by under 1% in
|
|
502
|
+
`many_roots` and `retained_activity`, where the gem reads the clock once
|
|
503
|
+
per root. The investigation scripts that seed through the same workload
|
|
504
|
+
load the clock too; `scalar_cost.rb` freezes time in front of it, so its
|
|
505
|
+
parity check still sees one instant.
|
|
506
|
+
|
|
6
507
|
## [0.14.0] - 2026-10-29
|
|
7
508
|
|
|
8
509
|
### Breaking changes
|
data/QUICKSTART.md
CHANGED
|
@@ -37,6 +37,19 @@ table. `--with-changes` adds `object_changes`, which PaperTrail uses for
|
|
|
37
37
|
for each event. This gem can also compare the full earlier records saved in
|
|
38
38
|
PaperTrail's `object` column.
|
|
39
39
|
|
|
40
|
+
PaperTrail stores earlier records as YAML, and Rails reads back only the YAML
|
|
41
|
+
classes you allow. Without this, reading the first version raises
|
|
42
|
+
`Psych::DisallowedClass`. Add PaperTrail's list to `config/application.rb`,
|
|
43
|
+
inside `class Application`:
|
|
44
|
+
|
|
45
|
+
<!-- executable:quickstart-config -->
|
|
46
|
+
```ruby
|
|
47
|
+
config.active_record.yaml_column_permitted_classes = [
|
|
48
|
+
ActiveRecord::Type::Time::Value, ActiveSupport::TimeWithZone, ActiveSupport::TimeZone,
|
|
49
|
+
BigDecimal, Date, Symbol, Time
|
|
50
|
+
]
|
|
51
|
+
```
|
|
52
|
+
|
|
40
53
|
## 2. Version a model
|
|
41
54
|
|
|
42
55
|
Create an article model and tell PaperTrail to track its changes:
|
|
@@ -233,10 +246,11 @@ The same `within:` option works on `activity_timeline`, `analyze`,
|
|
|
233
246
|
| Recent activity through now, for the records a relation selects | `report(scope, since:, limit:)` |
|
|
234
247
|
|
|
235
248
|
Use the batch methods for many records so they can share database queries.
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
249
|
+
A few scoped associations, such as one whose scope is SQL text, can be read
|
|
250
|
+
only with PT-AT, approximately and one record at a time. Every method rejects
|
|
251
|
+
them with `UnsupportedAssociationError`, naming the association; passing
|
|
252
|
+
`allow_approximate: true` accepts both costs. See
|
|
253
|
+
[costly associations](docs/reference.md#costly-associations).
|
|
240
254
|
|
|
241
255
|
When associations are included, `timeline` compares their values at the article's
|
|
242
256
|
versions. `activity_timeline` also reports the comments' own version events, even
|
|
@@ -388,6 +402,9 @@ window to select that article.
|
|
|
388
402
|
comments does not automatically include every association on each comment.
|
|
389
403
|
- Historical output cannot contain data that PaperTrail or PT-AT did not record
|
|
390
404
|
or can no longer reconstruct.
|
|
405
|
+
- A report with `since:` or `within:` gets slow as the version table grows
|
|
406
|
+
unless you add the
|
|
407
|
+
[two version indexes](docs/architecture.md#database-indexes).
|
|
391
408
|
|
|
392
409
|
For association support, performance, error handling, ignore rules, and all
|
|
393
410
|
available result methods, see the
|