paper_trail_diff 0.17.1 → 0.18.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 +648 -0
- data/QUICKSTART.md +12 -14
- data/README.md +32 -30
- data/docs/architecture.md +65 -29
- data/docs/performance.md +161 -46
- data/docs/reference.md +495 -394
- data/docs/testing.md +9 -15
- data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +42 -9
- data/lib/paper_trail_diff/activity_boundary.rb +15 -6
- data/lib/paper_trail_diff/activity_child_candidate_loader.rb +91 -18
- data/lib/paper_trail_diff/activity_collection_event_applier.rb +14 -15
- data/lib/paper_trail_diff/activity_collection_record_updater.rb +18 -8
- data/lib/paper_trail_diff/activity_collection_route_updater.rb +12 -25
- data/lib/paper_trail_diff/activity_event.rb +53 -34
- data/lib/paper_trail_diff/activity_event_record_normalizer.rb +12 -26
- data/lib/paper_trail_diff/activity_event_record_resolver.rb +45 -32
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +26 -33
- data/lib/paper_trail_diff/activity_history.rb +28 -34
- data/lib/paper_trail_diff/activity_relationship.rb +3 -26
- data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +14 -8
- data/lib/paper_trail_diff/activity_snapshot_delta.rb +2 -3
- data/lib/paper_trail_diff/activity_snapshot_sequence.rb +92 -25
- data/lib/paper_trail_diff/activity_timeline_builder.rb +128 -77
- data/lib/paper_trail_diff/activity_transaction_applier.rb +49 -0
- data/lib/paper_trail_diff/activity_tree_filter.rb +70 -57
- data/lib/paper_trail_diff/activity_tree_places.rb +76 -0
- data/lib/paper_trail_diff/activity_version_collector.rb +45 -32
- data/lib/paper_trail_diff/activity_view.rb +2 -0
- data/lib/paper_trail_diff/analysis.rb +6 -5
- data/lib/paper_trail_diff/analysis_batch.rb +21 -17
- data/lib/paper_trail_diff/association_activity_edge.rb +99 -85
- data/lib/paper_trail_diff/association_activity_selection.rb +46 -14
- data/lib/paper_trail_diff/association_discovery.rb +4 -4
- data/lib/paper_trail_diff/association_key.rb +10 -18
- data/lib/paper_trail_diff/association_traversal.rb +72 -92
- data/lib/paper_trail_diff/batch_boundary_resolver.rb +1 -7
- data/lib/paper_trail_diff/batch_preload.rb +2 -3
- data/lib/paper_trail_diff/batched_root_analyses.rb +60 -25
- data/lib/paper_trail_diff/batched_root_analyzer.rb +5 -5
- data/lib/paper_trail_diff/batched_root_versions.rb +7 -30
- data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -14
- data/lib/paper_trail_diff/candidate_table.rb +160 -0
- data/lib/paper_trail_diff/change_attribution.rb +15 -23
- data/lib/paper_trail_diff/collection_identity_index.rb +68 -24
- data/lib/paper_trail_diff/collection_transition.rb +3 -3
- data/lib/paper_trail_diff/comparison_batch.rb +13 -6
- data/lib/paper_trail_diff/database_time.rb +85 -0
- data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -23
- data/lib/paper_trail_diff/deleted_root_filter.rb +10 -6
- data/lib/paper_trail_diff/diagnostics.rb +26 -86
- data/lib/paper_trail_diff/endpoint.rb +37 -5
- data/lib/paper_trail_diff/engine.rb +1 -1
- data/lib/paper_trail_diff/errors.rb +0 -6
- data/lib/paper_trail_diff/exact_column_type.rb +96 -0
- data/lib/paper_trail_diff/historical_snapshot_store.rb +88 -83
- data/lib/paper_trail_diff/instrumentation.rb +0 -8
- data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -4
- data/lib/paper_trail_diff/live_graph_collector.rb +1 -3
- data/lib/paper_trail_diff/nested_comparator.rb +42 -10
- data/lib/paper_trail_diff/paper_trail_adapter.rb +55 -98
- data/lib/paper_trail_diff/prepared_activity_index.rb +214 -182
- data/lib/paper_trail_diff/prepared_child_candidates.rb +13 -3
- data/lib/paper_trail_diff/prepared_edge_loader.rb +11 -49
- data/lib/paper_trail_diff/prepared_history.rb +27 -177
- data/lib/paper_trail_diff/prepared_history_loader.rb +39 -57
- data/lib/paper_trail_diff/prepared_record_index.rb +221 -147
- data/lib/paper_trail_diff/prepared_snapshot_builder.rb +47 -42
- data/lib/paper_trail_diff/prepared_state_association_reader.rb +85 -62
- data/lib/paper_trail_diff/recorded_changes.rb +34 -10
- data/lib/paper_trail_diff/recorded_owner.rb +67 -0
- data/lib/paper_trail_diff/root_version_selection.rb +6 -2
- data/lib/paper_trail_diff/scope_condition.rb +120 -80
- data/lib/paper_trail_diff/scope_ranking.rb +14 -32
- data/lib/paper_trail_diff/scoped_analysis.rb +11 -6
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -11
- data/lib/paper_trail_diff/scoped_root_selection.rb +91 -85
- data/lib/paper_trail_diff/selection_window.rb +31 -0
- data/lib/paper_trail_diff/snapshot.rb +60 -58
- data/lib/paper_trail_diff/snapshot_members.rb +115 -0
- data/lib/paper_trail_diff/snapshot_normalizer.rb +0 -11
- data/lib/paper_trail_diff/step.rb +1 -5
- data/lib/paper_trail_diff/stored_form.rb +146 -0
- data/lib/paper_trail_diff/stored_json_values.rb +8 -5
- data/lib/paper_trail_diff/stored_time_precision.rb +67 -33
- data/lib/paper_trail_diff/stored_values.rb +35 -3
- data/lib/paper_trail_diff/support.rb +185 -35
- data/lib/paper_trail_diff/time_of_day.rb +13 -2
- data/lib/paper_trail_diff/time_range.rb +85 -11
- data/lib/paper_trail_diff/time_version_range.rb +5 -1
- data/lib/paper_trail_diff/timeline_builder.rb +5 -11
- data/lib/paper_trail_diff/timeline_range.rb +56 -19
- data/lib/paper_trail_diff/timeline_snapshot_provider.rb +31 -7
- data/lib/paper_trail_diff/total_order.rb +19 -5
- data/lib/paper_trail_diff/transaction_anchors.rb +138 -0
- data/lib/paper_trail_diff/transaction_cut.rb +67 -327
- data/lib/paper_trail_diff/transaction_ends.rb +194 -0
- data/lib/paper_trail_diff/traversal_preparer.rb +12 -24
- data/lib/paper_trail_diff/{approximate_paths.rb → unreadable_paths.rb} +8 -9
- data/lib/paper_trail_diff/value_objects.rb +8 -6
- data/lib/paper_trail_diff/version.rb +1 -1
- data/lib/paper_trail_diff/version_association_candidate_scope.rb +12 -10
- data/lib/paper_trail_diff/version_boundary.rb +0 -29
- data/lib/paper_trail_diff/version_query.rb +49 -1
- data/lib/paper_trail_diff/version_scope_filter.rb +74 -5
- data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -31
- data/lib/paper_trail_diff/version_table.rb +8 -1
- data/lib/paper_trail_diff.rb +56 -110
- data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +24 -2
- data/sig/generated/paper_trail_diff/activity_boundary.rbs +6 -0
- data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +46 -5
- data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +7 -4
- data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +11 -2
- data/sig/generated/paper_trail_diff/activity_collection_route_updater.rbs +8 -6
- data/sig/generated/paper_trail_diff/activity_event.rbs +27 -18
- data/sig/generated/paper_trail_diff/activity_event_record_normalizer.rbs +7 -11
- data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +26 -8
- data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +10 -2
- data/sig/generated/paper_trail_diff/activity_history.rbs +23 -26
- data/sig/generated/paper_trail_diff/activity_relationship.rbs +0 -6
- data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +5 -0
- data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +53 -10
- data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +64 -38
- data/sig/generated/paper_trail_diff/activity_transaction_applier.rbs +28 -0
- data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +46 -38
- data/sig/generated/paper_trail_diff/activity_tree_places.rbs +45 -0
- data/sig/generated/paper_trail_diff/activity_version_collector.rbs +21 -11
- data/sig/generated/paper_trail_diff/analysis.rbs +6 -5
- data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -6
- data/sig/generated/paper_trail_diff/association_activity_edge.rbs +58 -45
- data/sig/generated/paper_trail_diff/association_activity_selection.rbs +20 -3
- data/sig/generated/paper_trail_diff/association_discovery.rbs +2 -2
- data/sig/generated/paper_trail_diff/association_key.rbs +2 -11
- data/sig/generated/paper_trail_diff/association_traversal.rbs +43 -44
- data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +0 -2
- data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +40 -17
- data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +2 -2
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -11
- data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +12 -8
- data/sig/generated/paper_trail_diff/candidate_table.rbs +97 -0
- data/sig/generated/paper_trail_diff/change_attribution.rbs +9 -16
- data/sig/generated/paper_trail_diff/collection_identity_index.rbs +33 -13
- data/sig/generated/paper_trail_diff/collection_transition.rbs +2 -2
- data/sig/generated/paper_trail_diff/comparison_batch.rbs +5 -0
- data/sig/generated/paper_trail_diff/database_time.rbs +48 -0
- data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +13 -15
- data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +4 -0
- data/sig/generated/paper_trail_diff/diagnostics.rbs +13 -31
- data/sig/generated/paper_trail_diff/endpoint.rbs +14 -1
- data/sig/generated/paper_trail_diff/errors.rbs +0 -8
- data/sig/generated/paper_trail_diff/exact_column_type.rbs +51 -0
- data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +51 -31
- data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -5
- data/sig/generated/paper_trail_diff/nested_comparator.rbs +21 -0
- data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +18 -29
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +138 -94
- data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +10 -2
- data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -21
- data/sig/generated/paper_trail_diff/prepared_history.rbs +22 -79
- data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +24 -32
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +137 -63
- data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +22 -13
- data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +41 -28
- data/sig/generated/paper_trail_diff/recorded_changes.rbs +19 -3
- data/sig/generated/paper_trail_diff/recorded_owner.rbs +39 -0
- data/sig/generated/paper_trail_diff/root_version_selection.rbs +4 -1
- data/sig/generated/paper_trail_diff/scope_condition.rbs +65 -52
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -23
- data/sig/generated/paper_trail_diff/scoped_analysis.rbs +11 -6
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +7 -2
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -43
- data/sig/generated/paper_trail_diff/selection_window.rbs +19 -0
- data/sig/generated/paper_trail_diff/snapshot.rbs +37 -38
- data/sig/generated/paper_trail_diff/snapshot_members.rbs +58 -0
- data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +0 -4
- data/sig/generated/paper_trail_diff/stored_form.rbs +63 -0
- data/sig/generated/paper_trail_diff/stored_json_values.rbs +0 -2
- data/sig/generated/paper_trail_diff/stored_time_precision.rbs +33 -20
- data/sig/generated/paper_trail_diff/stored_values.rbs +18 -2
- data/sig/generated/paper_trail_diff/support.rbs +96 -16
- data/sig/generated/paper_trail_diff/time_of_day.rbs +4 -0
- data/sig/generated/paper_trail_diff/time_range.rbs +49 -4
- data/sig/generated/paper_trail_diff/time_version_range.rbs +3 -0
- data/sig/generated/paper_trail_diff/timeline_builder.rbs +3 -6
- data/sig/generated/paper_trail_diff/timeline_range.rbs +29 -8
- data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -4
- data/sig/generated/paper_trail_diff/total_order.rbs +9 -3
- data/sig/generated/paper_trail_diff/transaction_anchors.rbs +80 -0
- data/sig/generated/paper_trail_diff/transaction_cut.rbs +43 -176
- data/sig/generated/paper_trail_diff/transaction_ends.rbs +124 -0
- data/sig/generated/paper_trail_diff/traversal_preparer.rbs +6 -11
- data/sig/generated/paper_trail_diff/{approximate_paths.rbs → unreadable_paths.rbs} +6 -7
- data/sig/generated/paper_trail_diff/value_objects.rbs +4 -2
- data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +11 -5
- data/sig/generated/paper_trail_diff/version_boundary.rbs +0 -14
- data/sig/generated/paper_trail_diff/version_query.rbs +26 -0
- data/sig/generated/paper_trail_diff/version_scope_filter.rbs +28 -2
- data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +4 -15
- data/sig/generated/paper_trail_diff/version_table.rbs +4 -0
- data/sig/generated/paper_trail_diff.rbs +22 -23
- metadata +28 -20
- data/lib/paper_trail_diff/activity_target_candidate_loader.rb +0 -123
- data/lib/paper_trail_diff/fallback_paths.rb +0 -35
- data/lib/paper_trail_diff/habtm_transaction_owners.rb +0 -70
- data/lib/paper_trail_diff/historical_association_reifier.rb +0 -161
- data/lib/paper_trail_diff/historical_filter.rb +0 -210
- data/lib/paper_trail_diff/own_window.rb +0 -35
- data/lib/paper_trail_diff/prepared_association_reifier.rb +0 -51
- data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +0 -74
- data/sig/generated/paper_trail_diff/fallback_paths.rbs +0 -22
- data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +0 -41
- data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +0 -58
- data/sig/generated/paper_trail_diff/historical_filter.rbs +0 -96
- data/sig/generated/paper_trail_diff/own_window.rbs +0 -22
- data/sig/generated/paper_trail_diff/prepared_association_reifier.rbs +0 -27
data/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,614 @@
|
|
|
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.18.0] - 2026-11-15
|
|
7
|
+
|
|
8
|
+
### Breaking changes
|
|
9
|
+
|
|
10
|
+
- `report` with `associations:` now defaults to `group: :transaction`, so each
|
|
11
|
+
save of a record and its associated records is one activity step, with every
|
|
12
|
+
version of that save in `step.sources`. Pass `group: nil` for the previous
|
|
13
|
+
step per version. A `report` without `associations:`, and `analyze`,
|
|
14
|
+
`analyze_many`, and `analyze_scope`, are unchanged.
|
|
15
|
+
|
|
16
|
+
- `PaperTrailDiff.timeline` and `PaperTrailDiff.activity_timeline` are
|
|
17
|
+
removed. Each returned what `analyze` already returns alongside its diff,
|
|
18
|
+
from the same read:
|
|
19
|
+
|
|
20
|
+
```ruby
|
|
21
|
+
PaperTrailDiff.timeline(article, **options)
|
|
22
|
+
# becomes
|
|
23
|
+
PaperTrailDiff.analyze(article, **options).timeline
|
|
24
|
+
|
|
25
|
+
PaperTrailDiff.activity_timeline(article, **options)
|
|
26
|
+
# becomes
|
|
27
|
+
PaperTrailDiff.analyze(article, activity: true, **options).activity_timeline
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The options are the same. The `activity_timeline.paper_trail_diff`
|
|
31
|
+
notification is replaced by `analyze.paper_trail_diff`, which every
|
|
32
|
+
`analyze` emits, with the same payload; its `step_count` counts the
|
|
33
|
+
activity timeline with `activity: true` and the root timeline without.
|
|
34
|
+
- `has_and_belongs_to_many` associations are no longer read. Naming one in
|
|
35
|
+
`associations:`, at the root or below it, raises
|
|
36
|
+
`UnsupportedAssociationError`, `association_paths` leaves it out, and
|
|
37
|
+
`supported_association_macros` no longer lists it. A join table has no
|
|
38
|
+
versions, so its history could only be read at the root's own
|
|
39
|
+
transaction-backed versions, never up to the current record, and not at
|
|
40
|
+
all with a scope or below the root. Replace it with a `has_many :through`
|
|
41
|
+
a join model that has `has_paper_trail`, as
|
|
42
|
+
[the reference shows](docs/reference.md#replacing-a-has_and_belongs_to_many):
|
|
43
|
+
add an `id` to the join table, and put `dependent: :destroy` on the
|
|
44
|
+
through association so that a member leaving saves a version. With it go
|
|
45
|
+
`UnsupportedLiveActivityError`, which only a `has_and_belongs_to_many`
|
|
46
|
+
raised, and the `habtm_transaction_shared`, `transaction_id_missing`, and
|
|
47
|
+
`transaction_id_column_missing` codes of `diagnose`.
|
|
48
|
+
- `allow_approximate:` is removed from every method, and no association is
|
|
49
|
+
read with PT-AT's reifier any more. An association whose scope history
|
|
50
|
+
cannot read, such as one that takes the owner or is written as SQL text,
|
|
51
|
+
raises `UnsupportedAssociationError` in every method that reads history:
|
|
52
|
+
PT-AT rebuilt it from its current members without checking the scope, so
|
|
53
|
+
a record that entered the scope since was reported as a member it was
|
|
54
|
+
not. Remove the path, or rewrite its scope as plain conditions on the
|
|
55
|
+
target's own columns. `diagnose` reports it as `unreadable_association`,
|
|
56
|
+
formerly `approximate_association`.
|
|
57
|
+
- `historical_filter:` and `max_filter_versions:` are removed from
|
|
58
|
+
`analyze_scope` and `report`, and `FilterLimitExceededError` with them.
|
|
59
|
+
Select records with the relation, which tests current values, and narrow
|
|
60
|
+
the changes reported with `version_scope:`.
|
|
61
|
+
- An association with a composite foreign key, or a `has_many :through`
|
|
62
|
+
that goes through one, raises `UnsupportedAssociationError`. It was read
|
|
63
|
+
with PT-AT's reifier, one record at a time and by timestamp alone.
|
|
64
|
+
- A polymorphic `belongs_to` whose record points at a class with a default
|
|
65
|
+
scope history cannot read raises `UnsupportedAssociationError` when that
|
|
66
|
+
record is read, instead of being read with PT-AT's reifier.
|
|
67
|
+
- The `ambiguous_association_boundary.paper_trail_diff` notification and
|
|
68
|
+
the `tied_version_timestamps` warning of `diagnose` are removed. Both
|
|
69
|
+
reported versions sharing a timestamp on a path PT-AT's reifier read;
|
|
70
|
+
every path is now read from loaded history, which orders such versions
|
|
71
|
+
by id.
|
|
72
|
+
|
|
73
|
+
### Added
|
|
74
|
+
|
|
75
|
+
- `ScopedAnalysis#total`, returned by `analyze_scope` and `report`, counts
|
|
76
|
+
the existing records the relation selects before its own `limit` and
|
|
77
|
+
`offset`, so a page of changed records can show how many pages there
|
|
78
|
+
are. A paged relation takes one more statement for it.
|
|
79
|
+
|
|
80
|
+
### Changed
|
|
81
|
+
|
|
82
|
+
- Activity reads what each version recorded unless `recorded_changes: false`
|
|
83
|
+
is passed; `recorded_changes: true` was needed before. Change rows
|
|
84
|
+
therefore credit each field's change to the version that recorded it, and
|
|
85
|
+
a write saved without a version, such as `update_columns`, gets a row of
|
|
86
|
+
its own with `unversioned?` true, instead of being credited to the
|
|
87
|
+
record's last version. `to_h(metadata: true)` on an activity step
|
|
88
|
+
includes each boundary's recorded changes.
|
|
89
|
+
- A transaction now takes effect where it saved its last version, in every
|
|
90
|
+
activity timeline. A window from `within:` or `since:` reports the
|
|
91
|
+
transactions that end inside it, each whole and under its own versions,
|
|
92
|
+
instead of moving its edges to where a transaction began. `analysis.window`
|
|
93
|
+
is therefore always the window you asked for, a step of a transaction that
|
|
94
|
+
began before the window can hold a version saved before it, and a
|
|
95
|
+
transaction group lists every version its transaction saved. The
|
|
96
|
+
`moved_window.paper_trail_diff` notification is gone, since no window
|
|
97
|
+
moves. Four things follow that you may notice:
|
|
98
|
+
- `timeline`, and a window without associations, report each version of the
|
|
99
|
+
record where it was saved, as before, but no longer move a window for a
|
|
100
|
+
transaction that also saved an associated record.
|
|
101
|
+
- `analyze_scope` and `report` select a record for a window by the versions
|
|
102
|
+
saved in it. A record whose transaction saves in the window and ends after
|
|
103
|
+
it is selected with nothing to report, and reported in the later window.
|
|
104
|
+
With associations, a window also selects by the versions that
|
|
105
|
+
transactions open at its start saved before it, since it reports those
|
|
106
|
+
transactions.
|
|
107
|
+
- `historical_filter:` reads each version where it was saved, so a record
|
|
108
|
+
whose transaction began before the window is checked from the state its
|
|
109
|
+
versions before the window left.
|
|
110
|
+
- With associations and `activity: true`, a window after a destroyed
|
|
111
|
+
record's last version reports nothing, or the deletion when the
|
|
112
|
+
transaction that destroyed the record ends inside the window, as
|
|
113
|
+
`analyze_scope` with `include_deleted: true` does. `analyze` and
|
|
114
|
+
`activity_timeline` raised `IncompleteTimeRangeError` there.
|
|
115
|
+
- A window with associations, with `activity: true` or without, runs one
|
|
116
|
+
more statement per version table, to find the transactions open at its
|
|
117
|
+
start, and no longer one per 250 records
|
|
118
|
+
for each edge, and `analyze_scope` and `report` run it once more to select
|
|
119
|
+
their records. A read with associations runs one more statement per 500
|
|
120
|
+
transactions its history holds, to read where each ends. See
|
|
121
|
+
[performance](docs/performance.md#what-still-grows).
|
|
122
|
+
|
|
123
|
+
- On SQL Server, a selection that reads its candidates in Ruby, as one with
|
|
124
|
+
`historical_filter:` or a version table whose `item_id` does not share the
|
|
125
|
+
key's type does, writes more than 500 of them to a temporary table once and
|
|
126
|
+
reads each page from it, instead of listing every id on every page. A
|
|
127
|
+
selection of 10,000 records took 0.6 s instead of 5 s, and one of 20,000
|
|
128
|
+
took 1.1 s instead of 30 s. A read that prevents writes, such as a replica
|
|
129
|
+
read through Rails' automatic role switching, still lists the ids, since
|
|
130
|
+
Active Record counts the table's statements as writes.
|
|
131
|
+
|
|
132
|
+
- An activity timeline no longer reads a whole association again for each
|
|
133
|
+
event of a transaction that saved more than one record in the tree, such
|
|
134
|
+
as two comments, or a comment and the article it touches. Each of the
|
|
135
|
+
transaction's versions is applied to the record it saved, as a version
|
|
136
|
+
alone in its transaction already was. One article with 1,000 comments and
|
|
137
|
+
1,000 transactions that each edited two of them took 1.9 s instead of
|
|
138
|
+
20.6 s, and 1.0 s instead of 18.8 s when each edited one comment and the
|
|
139
|
+
article. Results are unchanged.
|
|
140
|
+
|
|
141
|
+
- Replaying a `has_many` whose membership a version did not change no
|
|
142
|
+
longer sorts the collection again. A history of 3,200 comments edited
|
|
143
|
+
3,200 times took 1.8 s instead of 11 s.
|
|
144
|
+
|
|
145
|
+
- Reads with associations do less work, with the same results:
|
|
146
|
+
- A belongs_to target created inside an activity range no longer reads
|
|
147
|
+
its owners' branch again from history unless an owner holds no target.
|
|
148
|
+
An article with 1,000 comments, each given a newly created reviewer,
|
|
149
|
+
took 0.97 s instead of 28.5 s for `comments.reviewer`.
|
|
150
|
+
- Activity finds each owner's belongs_to targets in the states its history
|
|
151
|
+
already loaded, and no longer runs two more statements per belongs_to
|
|
152
|
+
path to read PT-AT's rows and the live rows.
|
|
153
|
+
- A window finds where the transactions open at its start began once,
|
|
154
|
+
before reading, instead of reading the window and then reading it again
|
|
155
|
+
from there; `analyze_scope` and `report` share that one statement
|
|
156
|
+
across record selection and every record of the model. A report with
|
|
157
|
+
an unrelated open transaction ran 19 statements instead of 27.
|
|
158
|
+
- `include_deleted:` with a relation that has no conditions, on a model
|
|
159
|
+
that is not a subclass, asks the version table which destroys stored a
|
|
160
|
+
state instead of decoding each one. 2,000 deleted articles took 37 ms
|
|
161
|
+
instead of 753 ms.
|
|
162
|
+
- A state read from JSON history converts only the attributes whose type
|
|
163
|
+
needs it, listed once per model, and a value already frozen throughout
|
|
164
|
+
is no longer walked again to keep it immutable. A report over records
|
|
165
|
+
with 100-key JSON values took 2.0 s instead of 2.4 s.
|
|
166
|
+
|
|
167
|
+
- Association scopes, and ranges and orders in them, are read in Ruby only on
|
|
168
|
+
the SQL column types the gem lists for each of SQLite, PostgreSQL, MySQL, and
|
|
169
|
+
SQL Server, instead of on any column Active Record casts as an integer,
|
|
170
|
+
boolean, string, date, or time. A column of another type, or on another
|
|
171
|
+
adapter, is now refused unless you pass `allow_approximate: true`, like any
|
|
172
|
+
scope the gem cannot read. On SQL Server this leaves out a legacy `datetime` or `smalldatetime` key, which
|
|
173
|
+
rounds the times it stores.
|
|
174
|
+
|
|
175
|
+
- A `has_many` or `has_one` whose target declares no `belongs_to` on its
|
|
176
|
+
foreign key, and a `has_many :through` with such a part, now raises
|
|
177
|
+
`UnsupportedAssociationError` up front in every method. `diagnose` reports
|
|
178
|
+
it as `:unsupported_association` and `association_paths` leaves it out.
|
|
179
|
+
PT-AT records a record's owner on the record's own versions, once for each
|
|
180
|
+
`belongs_to` it declares, so with none nothing said a record that was
|
|
181
|
+
destroyed or moved away had been in the association: `compare`, timelines,
|
|
182
|
+
analyses and `report` showed the records the association holds now and
|
|
183
|
+
silently left out the ones that left. Declare the `belongs_to` on the
|
|
184
|
+
target to request the path. Versions saved before then recorded no owner,
|
|
185
|
+
so a record that left before then is still not reported.
|
|
186
|
+
|
|
187
|
+
- A version now reads alike wherever it is used: as an endpoint of
|
|
188
|
+
`compare`, and as the start or the end of a range. Each reads the records
|
|
189
|
+
around it as they stood before every transaction that had not ended where
|
|
190
|
+
the version's own took effect, as windows already did. A range starts
|
|
191
|
+
before its first version's transaction took effect and ends where its last
|
|
192
|
+
version's took effect: what another transaction saved before the start is
|
|
193
|
+
in the starting state if that transaction ended first, and reported in its
|
|
194
|
+
own step if it ended later. `compare` used to read a version by when the
|
|
195
|
+
records around it were saved, and `from:` used to count everything saved
|
|
196
|
+
before it as settled. So two ranges that meet at a version now report each
|
|
197
|
+
change once, as the range over both does, and a range from a version
|
|
198
|
+
inside a transaction no longer reports another transaction's finished
|
|
199
|
+
change as its own. A read with associations of a range of versions runs one
|
|
200
|
+
more statement per version table, to find a transaction open at its start,
|
|
201
|
+
and one more to find where its last version's transaction ended.
|
|
202
|
+
- A destroyed record's history ends where its destruction took effect. A
|
|
203
|
+
window holding the destruction reports it even when another transaction
|
|
204
|
+
that saved in the tree before it ends later, and a change another
|
|
205
|
+
transaction committed in the tree before the destroying one ended is
|
|
206
|
+
reported in the window it ended in.
|
|
207
|
+
- Activity on the record alone, without associations, reports each version
|
|
208
|
+
where it was saved, as `timeline` does and as the reference said. A window
|
|
209
|
+
edge between two saves of one transaction no longer loses the first.
|
|
210
|
+
- With associations, `version_scope:` selects a record in `analyze_scope`
|
|
211
|
+
and `report` whenever its activity reports something: a version selects it
|
|
212
|
+
when the filter keeps any version of its transaction, as activity keeps
|
|
213
|
+
whole transactions.
|
|
214
|
+
- Values are compared in the form the database stores them, as the history
|
|
215
|
+
stores them: times to the column's precision (to 1/300 s on a SQL Server
|
|
216
|
+
`datetime`), MySQL `float` to single precision, SQLite decimals as the
|
|
217
|
+
numbers SQLite returns, and fixed-width `char` columns padded or stripped as
|
|
218
|
+
the database does. A record saved with a value the database rounds no
|
|
219
|
+
longer shows a change against its own version. `historical_filter:`
|
|
220
|
+
compares its expected values in the same form.
|
|
221
|
+
- A time of day reads in `ActiveRecord.default_timezone`, as Active Record
|
|
222
|
+
stores it, including one stored as JSON text with a date and an offset.
|
|
223
|
+
- Errors are raised up front with the gem's own classes: `analyze_scope` and
|
|
224
|
+
`report` on a model without PaperTrail raise `InvalidEndpointError`, and a
|
|
225
|
+
version class without an `object` column `ConfigurationError`;
|
|
226
|
+
`compare_many` with an unknown boundary symbol raises
|
|
227
|
+
`InvalidTimelineRangeError`; `version_scope:` is checked where it is given,
|
|
228
|
+
and must take the relation as its one argument and return it narrowed, or
|
|
229
|
+
an array of its versions; `report(since:)` must be a time, date or string;
|
|
230
|
+
boolean options must be `true` or `false`; a root with unsaved changes is
|
|
231
|
+
refused; a version loaded without `object` is refused; and a relation that
|
|
232
|
+
selects columns without the primary key raises `ConfigurationError`.
|
|
233
|
+
- `historical_filter:` refuses an attribute named twice, as a string and a
|
|
234
|
+
symbol.
|
|
235
|
+
- `diagnose` raises `ReversedEndpointsError` for two versions given newest
|
|
236
|
+
first, as `compare` does, instead of reporting `ok?`.
|
|
237
|
+
- `within:` and `since:` refuse a string that names no real day, such as
|
|
238
|
+
`"12"` or `"2026-02-30"`, which `Time.zone.parse` read as noon today and
|
|
239
|
+
as 2 March.
|
|
240
|
+
- `max_filter_versions:` is checked whether or not `historical_filter:` is
|
|
241
|
+
given, and `recorded_changes` refuses a version loaded without its
|
|
242
|
+
`object_changes` column instead of answering that it recorded nothing.
|
|
243
|
+
- `unreachable` and `deleted` list integer ids by value, so 2 comes before 10.
|
|
244
|
+
- A has_many or has_one read with associations runs one more statement per
|
|
245
|
+
read, for the first versions of children made without a version (see
|
|
246
|
+
Fixed).
|
|
247
|
+
- History reads every association member from its recorded state, including
|
|
248
|
+
members of a model whose records need their own initialization (an
|
|
249
|
+
`after_initialize` callback, the attribute API, encryption, or a default
|
|
250
|
+
scope that assigns), which it instantiates once per state to read as a
|
|
251
|
+
record would hold it. Such a member's foreign keys and type columns are
|
|
252
|
+
read from its stored attributes, as Active Record loads its associations,
|
|
253
|
+
rather than through a reader method the model overrides.
|
|
254
|
+
|
|
255
|
+
### Fixed
|
|
256
|
+
|
|
257
|
+
- On SQL Server, two `report` or `analyze_scope` calls with `associations:`
|
|
258
|
+
at the same time could deadlock in tempdb, and one raised
|
|
259
|
+
`ActiveRecord::DeadlockVictim`. The adapter read the candidate table's
|
|
260
|
+
columns from tempdb's catalog before each fill, which another call's
|
|
261
|
+
`DROP TABLE` held locks on. The table is now filled by statements the
|
|
262
|
+
adapter does not inspect, which also saves a catalog query per call.
|
|
263
|
+
- `report` and `analyze_scope` now select the record a child left when the
|
|
264
|
+
child's first version is the update that moved or detached it, such as a
|
|
265
|
+
row from before PaperTrail was installed. They read the old owner from
|
|
266
|
+
that version's stored state, as an activity analysis does, at every level
|
|
267
|
+
of a path and for the join rows of a `has_many :through`. Each `has_many`
|
|
268
|
+
or `has_one` edge on a path runs one more statement for each source of
|
|
269
|
+
changes below it.
|
|
270
|
+
- `report(associations: nil)` raises `ConfigurationError` naming the option,
|
|
271
|
+
as `analyze_scope` does, instead of `NoMethodError`.
|
|
272
|
+
|
|
273
|
+
- On SQL Server, `analyze_scope` and `report` with `associations:` select
|
|
274
|
+
their records from a temporary table that each candidate subquery fills
|
|
275
|
+
in turn, rather than from one statement joining the subqueries with `OR`,
|
|
276
|
+
which SQL Server planned to run the associations' subqueries once per
|
|
277
|
+
record. Selecting the orders changed in a week, among 1,600 with line
|
|
278
|
+
items, took 35 s, past the adapter's default 5 s timeout, and now takes
|
|
279
|
+
0.4 s. A read that prevents writes still uses the single statement.
|
|
280
|
+
- A `belongs_to` whose class is an STI subclass no longer keeps a target
|
|
281
|
+
that an update retyped out of the subclass, or misses one retyped into
|
|
282
|
+
it. The change was reported at the next event, under that event's author.
|
|
283
|
+
- A polymorphic `belongs_to` with an id and no type reads as no target, as
|
|
284
|
+
Active Record reads it. History holding such a state raised
|
|
285
|
+
`UnsupportedAssociationError`.
|
|
286
|
+
- A date assigned to a datetime column, which Active Record leaves on the
|
|
287
|
+
instance when time zone aware attributes are off or `update_columns`
|
|
288
|
+
writes it, and PaperTrail stores from there, is read as midnight in
|
|
289
|
+
Active Record's default time zone, as the database keeps it. It was read
|
|
290
|
+
in `Time.zone`, or kept as a Date, so a version and the unchanged row
|
|
291
|
+
differed.
|
|
292
|
+
- The digits JSON history keeps for a time are read from what its writer
|
|
293
|
+
writes, a custom serializer that wraps PaperTrail's JSON one included.
|
|
294
|
+
They were assumed from Active Support's setting, so such a serializer, or
|
|
295
|
+
the legacy JSON format that writes whole seconds, read every unchanged
|
|
296
|
+
time as changed.
|
|
297
|
+
- An attribute a model declares without a column, such as a form field, is
|
|
298
|
+
left out of every diff, change row and snapshot, as no row holds it.
|
|
299
|
+
PaperTrail stores whatever the instance held for it. `historical_filter:`
|
|
300
|
+
refuses it as an unknown attribute, as `where` cannot name it.
|
|
301
|
+
- `historical_filter:` reads text or a date given for a datetime attribute
|
|
302
|
+
as `where` does, in the database's time zone. In any zone but UTC the two
|
|
303
|
+
selected different records. A value its attribute cannot take, such as a
|
|
304
|
+
Hash for a time, raises `ConfigurationError` instead of Active Record's
|
|
305
|
+
own error.
|
|
306
|
+
- `nested_changes` tells 1 from 1.0 inside arrays, as under a hash key and
|
|
307
|
+
as the attribute diff does.
|
|
308
|
+
- In `analyze_many` and `report`, a root that sits in another root's tree
|
|
309
|
+
is read there from the versions loaded for it. Its window's versions were
|
|
310
|
+
used instead, so the other root could report a record that joined it
|
|
311
|
+
only after the window, with the values it got then.
|
|
312
|
+
- `analyze_many` with associations and `activity: true` gives a root with
|
|
313
|
+
no versions an empty analysis over its whole history, as `analyze` does.
|
|
314
|
+
It raised `IncompleteTimeRangeError`.
|
|
315
|
+
- A `has_one :through` with no order reads, in history, the target Active
|
|
316
|
+
Record reads: that of its first join row by key on SQLite, PostgreSQL and
|
|
317
|
+
MySQL, and the target with the lowest id on SQL Server. It read the
|
|
318
|
+
lowest id everywhere. With two join rows, a diff from a past version to
|
|
319
|
+
the unchanged record reported it replaced.
|
|
320
|
+
- Activity on a path below an association to an STI subclass no longer
|
|
321
|
+
raises `UnknownAssociationError` when a child is retyped to its base class
|
|
322
|
+
and back.
|
|
323
|
+
- `report` and `analyze_scope` select a root whose change sits below a row
|
|
324
|
+
saved without versions, such as one from before PaperTrail, as `analyze`
|
|
325
|
+
reports it. Such a row holds its live key throughout.
|
|
326
|
+
- With `version_scope:`, an analysis ends after the last change the filter
|
|
327
|
+
keeps. A kept version of a record that had left the tree moved its end to
|
|
328
|
+
the next event, so its `diff` and `to_snapshot` held a change the filter
|
|
329
|
+
drops.
|
|
330
|
+
- A record moved by its own update is credited, in `change_rows`, to that
|
|
331
|
+
version. Two records moved in one transaction were both credited to the
|
|
332
|
+
last version the step read.
|
|
333
|
+
- `compare` from a version saved outside a transaction, as
|
|
334
|
+
`save_with_version` saves one, reads a transaction still open there as
|
|
335
|
+
open, as the range from that version does. Such a comparison runs one more
|
|
336
|
+
statement, to find where the history's transactions end.
|
|
337
|
+
- `report` and `analyze_scope` with associations no longer select a record
|
|
338
|
+
that changed only before the window while an unrelated transaction was
|
|
339
|
+
open across its start. Before the start, only the versions of the
|
|
340
|
+
transactions open there select a record. Such records came back with
|
|
341
|
+
nothing to report, counted toward `limit:`, and a destroyed one was listed
|
|
342
|
+
in `unreachable`.
|
|
343
|
+
- A transaction takes effect at its latest dated version, ids breaking a
|
|
344
|
+
tie, and is open across a window's start when it has versions dated on
|
|
345
|
+
both sides. A callback or nested save declared before `has_paper_trail`
|
|
346
|
+
saves other records' versions first and its own last, dated as its save
|
|
347
|
+
began. The transaction was placed at its last version by id, so another
|
|
348
|
+
transaction's edit of the same record was reported by no step, and two
|
|
349
|
+
windows cut between its dates reported its change in neither.
|
|
350
|
+
- Two ranges that meet at the destroy version of a record restored later
|
|
351
|
+
under its id report its removal once, in the range from the destroy. A
|
|
352
|
+
window over the record's earlier life credits the transaction that
|
|
353
|
+
restored it as a window that begins after the destruction does.
|
|
354
|
+
|
|
355
|
+
- Comparing a JSON array that holds a BigDecimal NaN or infinity no longer
|
|
356
|
+
raises `FloatDomainError`; it compares as a Float NaN or infinity did.
|
|
357
|
+
- An activity timeline no longer leaves a record as it was at one of two
|
|
358
|
+
places a path reaches it. An article read with
|
|
359
|
+
`associations: ["author.articles"]` is the root and one of its author's
|
|
360
|
+
articles; a comment read with `["article.comments"]` is one of its
|
|
361
|
+
article's comments; under `["articles.comments.article"]` an article is a
|
|
362
|
+
member of a collection and the target of a `belongs_to` below it; and a
|
|
363
|
+
polymorphic `belongs_to` can point back at any record in the tree. An
|
|
364
|
+
event on such a record changed it at one place only. The step and any
|
|
365
|
+
window around it then missed the change at the other, and the next event
|
|
366
|
+
in that branch reported it, credited to its own author in `change_rows`.
|
|
367
|
+
Such an event now has the branches that hold the record read again, or
|
|
368
|
+
the whole snapshot for the root, which costs the size of what is read. See
|
|
369
|
+
[performance](docs/performance.md#what-still-grows). `compare` and
|
|
370
|
+
`timeline` were not affected.
|
|
371
|
+
|
|
372
|
+
- `activity_timeline`, `analyze` with `activity: true`, `analyze_many`, and
|
|
373
|
+
`report` no longer raise `ConfigurationError` ("prepared activity graph is
|
|
374
|
+
missing ...") for a path that continues past a `belongs_to` when no record
|
|
375
|
+
read had one, such as `associations: ["article.author"]` on a comment
|
|
376
|
+
created without an article. They read the record with nothing on that path.
|
|
377
|
+
|
|
378
|
+
- An activity timeline no longer reads a whole collection again for each event
|
|
379
|
+
that put a record into it or took one out. A snapshot kept a table of its
|
|
380
|
+
records' positions, and built it again and checked their order again
|
|
381
|
+
whenever its members changed, so a replay's time grew with its events times
|
|
382
|
+
the size of the collection: 3,000 comments created one at a time on one
|
|
383
|
+
article took 19.2 s to replay and now take 3.6 s, and 1,000 took 2.1 s and
|
|
384
|
+
now take 0.7 s. Edits were not affected. A record is now found by searching
|
|
385
|
+
the order a snapshot holds its records in. See
|
|
386
|
+
[performance](docs/performance.md#what-still-grows).
|
|
387
|
+
|
|
388
|
+
- A `has_many` or `has_one` whose owners use single-table inheritance no
|
|
389
|
+
longer loses the records that left it when the target's `belongs_to` names
|
|
390
|
+
another class of the owners' table than the owner's own or its base class.
|
|
391
|
+
With `Doc`, `Report < Doc` and `AnnualReport < Report`, and notes that
|
|
392
|
+
`belongs_to :report`, a note destroyed or moved away from an annual report
|
|
393
|
+
was missing from `compare`, timelines and analyses, and when `Doc` declared
|
|
394
|
+
the association, `analyze_scope` and `report` did not select a record whose
|
|
395
|
+
only change was such a note. PT-AT records the class the `belongs_to` names,
|
|
396
|
+
and the gem looked for the owner's class and its base class only.
|
|
397
|
+
|
|
398
|
+
- `analyze_scope` and `report` over a window no longer slow down with the size
|
|
399
|
+
of the model's table on PostgreSQL. The statement that finds the records
|
|
400
|
+
changed in the window and deleted since asked with `NOT IN (SELECT id ...)`,
|
|
401
|
+
which PostgreSQL does not plan as an anti-join: it reads every id of the
|
|
402
|
+
table, and reads them again for each version in the window once they
|
|
403
|
+
outgrow `work_mem`. With 2 million articles and 2,000 of them edited in the
|
|
404
|
+
window, a `report` took 16 s and now takes 1.4 s, and with 500,000 it took
|
|
405
|
+
11 s and now takes 1.5 s. That statement, and the one like it for records
|
|
406
|
+
selected by their associations, now asks with `NOT EXISTS`. Results are
|
|
407
|
+
unchanged. See [performance](docs/performance.md#database-indexes).
|
|
408
|
+
|
|
409
|
+
- An activity timeline over a tree no longer slows down with the tree's size
|
|
410
|
+
times its events. Each event of an associated record is checked against the
|
|
411
|
+
snapshots around its transaction, to leave out a record that was outside
|
|
412
|
+
the tree, and each check looked through every collection of the snapshot.
|
|
413
|
+
The records each snapshot holds are now kept up from one snapshot to the
|
|
414
|
+
next, by what its event changed. 2,000 replies created one at a time under
|
|
415
|
+
2,000 comments of one article took 10.4 s to replay and now take 1.4 s, and
|
|
416
|
+
3,000 comments created one at a time took 3.6 s and now take 1.8 s. A window
|
|
417
|
+
with `activity: true` on a record not saved since the window, with 2,000
|
|
418
|
+
comments created after it, took 1.8 s and now takes 0.8 s. Results are
|
|
419
|
+
unchanged.
|
|
420
|
+
|
|
421
|
+
- A range that ended in the past no longer slows down with the children its
|
|
422
|
+
records have gained since. A `has_many` or `has_one` read every child that
|
|
423
|
+
was ever its owner's from the range's start onward, with each child's row
|
|
424
|
+
and versions, and only then left out those created after the range. With
|
|
425
|
+
2,000 comments added to an article after the range, a `compare` of two of
|
|
426
|
+
its versions took 132 ms and now takes 10 ms, as with none, and `timeline`
|
|
427
|
+
between them, or `analyze` over a window that a later version of the article
|
|
428
|
+
ends, went from about 160 ms to about 12 ms. A child is left out when its
|
|
429
|
+
first version is a `create` saved after the range's end, so one whose
|
|
430
|
+
creation was never recorded is still read. Where `item_id` is not stored as
|
|
431
|
+
the child's key is, as with a string `item_id` and integer keys, the child's
|
|
432
|
+
current row is still read, though not its versions. Results are unchanged.
|
|
433
|
+
|
|
434
|
+
- An association scope that negates an empty list along with another
|
|
435
|
+
condition, such as `where.not(status: [], score: 1)`, now reads a record
|
|
436
|
+
whose `status` is NULL as the database does. Active Record writes the empty
|
|
437
|
+
list as a condition that is always false, so the negation is true for every
|
|
438
|
+
record, but history read it against a NULL as unknown and left the record
|
|
439
|
+
out, reporting a current member as added.
|
|
440
|
+
|
|
441
|
+
- `recorded_changes`, and change rows with `recorded_changes: true`, now cast
|
|
442
|
+
the values a `json` or `jsonb` `object_changes` column stores. PaperTrail
|
|
443
|
+
leaves such a column's dates, times, and decimals as the strings JSON gives
|
|
444
|
+
back, and the gem returned them that way: a recorded change no longer
|
|
445
|
+
equalled the state it produced, so one change became three change rows, two
|
|
446
|
+
of them credited to writes without a version, and a model with a `time`
|
|
447
|
+
column raised `NoMethodError`.
|
|
448
|
+
|
|
449
|
+
- A report with `historical_filter:` can be paged with the relation, as the
|
|
450
|
+
reference says. A relation with a `limit` now reads its candidates in its
|
|
451
|
+
own order and stops matching when the page is full, and only the page
|
|
452
|
+
counts toward `limit:`. Before, every match counted, so
|
|
453
|
+
`Article.order(:id).limit(20)` with `limit: 20` raised
|
|
454
|
+
`BatchLimitExceededError` whenever more than 20 records matched, and the
|
|
455
|
+
history of every match was read to return one page.
|
|
456
|
+
|
|
457
|
+
- A hash `historical_filter:` now works on a model with an encrypted
|
|
458
|
+
attribute, and on a version that names a column since dropped. It raised
|
|
459
|
+
"cannot read recorded attributes directly"; such a version is now rebuilt
|
|
460
|
+
as PaperTrail rebuilds it and compared by its decrypted, cast values.
|
|
461
|
+
|
|
462
|
+
- A hash `historical_filter:` with a list or a range as a value, such as
|
|
463
|
+
`{ status: %i[published archived] }`, raises `ConfigurationError` instead
|
|
464
|
+
of matching nothing. `where` would match any of the values; a filter
|
|
465
|
+
compares one, so use a callable for several. A list is still the value of
|
|
466
|
+
an attribute that holds one, such as a serialized or an array column.
|
|
467
|
+
|
|
468
|
+
- `include_deleted: true`, and a readable association scope, accept an
|
|
469
|
+
equality or a list on a date or a time column, such as `where(due: date)`,
|
|
470
|
+
wherever they already accepted a range on it. Before, the relation was
|
|
471
|
+
refused, or the scope read by its slower path.
|
|
472
|
+
|
|
473
|
+
- `version_scope:` raises `ConfigurationError` when the callable returns
|
|
474
|
+
anything but a relation on the version class it was given. A callable that
|
|
475
|
+
returned another model's relation, such as `Document.all`, silently
|
|
476
|
+
selected the versions whose ids equalled that model's ids.
|
|
477
|
+
|
|
478
|
+
- A relation ordered by another table's key written in quotes, such as
|
|
479
|
+
`order('accounts."id"')`, is no longer read as ordered by the model's own
|
|
480
|
+
key, so its pages get the tie-breaker they need.
|
|
481
|
+
|
|
482
|
+
- `recorded_changes(version)` leaves out a name the model no longer has,
|
|
483
|
+
such as a column dropped since, as diffs, timelines, and change rows do.
|
|
484
|
+
|
|
485
|
+
- `nested_changes` compares two arrays in time proportional to their length.
|
|
486
|
+
Arrays of objects took time proportional to its square: 16,000 objects
|
|
487
|
+
took 53 s and now take 0.2 s. Results are unchanged.
|
|
488
|
+
|
|
489
|
+
- Without `activity:`, `analyze`, `analyze_many`, `analyze_scope` and
|
|
490
|
+
`timeline` with associations could report an associated record's change
|
|
491
|
+
backwards, and then again forwards, when two transactions interleaved: one
|
|
492
|
+
edited a comment, another saved the article, and the first then saved the
|
|
493
|
+
article too. The comment read as edited at the other transaction's version
|
|
494
|
+
and as not yet edited at its own. Whether it did depended on how far back
|
|
495
|
+
the history read went, so `analyze_many` could disagree with `analyze` for
|
|
496
|
+
the same record. These reads now place each associated record's change
|
|
497
|
+
where its transaction ends, as activity does, and report it once. They
|
|
498
|
+
run the statements activity runs for that: one per version table for a
|
|
499
|
+
window, to find the transactions open at its start, and one per 500
|
|
500
|
+
transactions the history holds.
|
|
501
|
+
- `analyze_many`, `analyze_scope` and `report` without a window could read
|
|
502
|
+
a record's history differently from `analyze`, when a transaction changed
|
|
503
|
+
an associated record before the record's first version and ended after it,
|
|
504
|
+
such as one that renamed an author and later saved an article created in
|
|
505
|
+
between. The batch reported the rename as a change in the article's
|
|
506
|
+
history, once backwards and once forwards, because its history also held
|
|
507
|
+
an older record's versions. A history without a window now
|
|
508
|
+
begins at the record's first version, however it is read.
|
|
509
|
+
- Two transactions that saved in one record's tree at the same time
|
|
510
|
+
interleave their versions, and activity timelines read them wrongly in four
|
|
511
|
+
ways, all fixed by reading each transaction where it ends:
|
|
512
|
+
- A change could be credited to the other transaction's author, such as a
|
|
513
|
+
comment one transaction removed reported under the one that saved
|
|
514
|
+
meanwhile.
|
|
515
|
+
- Back-to-back windows that met inside such a transaction could report one
|
|
516
|
+
of its changes in neither window.
|
|
517
|
+
- Back-to-back windows could report a change in both, when a transaction
|
|
518
|
+
saved an associated record before the record itself, around another
|
|
519
|
+
transaction.
|
|
520
|
+
- A window that started inside a transaction credited an edit the
|
|
521
|
+
transaction saved before the window to the version of another record.
|
|
522
|
+
- A transaction that went on to save a record outside the requested paths,
|
|
523
|
+
such as a comment moved to another article, was placed at its last version
|
|
524
|
+
on them, which depends on where a window starts. Back-to-back windows could
|
|
525
|
+
then report one of its changes in neither. Where a transaction ends is now
|
|
526
|
+
read from its version table, whatever records it saved.
|
|
527
|
+
- A range that ended while a transaction saving in the tree was still open
|
|
528
|
+
read the records it had saved as changed. They now read as they stood
|
|
529
|
+
before it, since it had not ended.
|
|
530
|
+
- A window that started while a transaction was open read a record that
|
|
531
|
+
transaction had already saved as changed, when the transaction saved
|
|
532
|
+
nothing else of the tree inside the window. Its snapshot then disagreed
|
|
533
|
+
with the one the window before it ended on.
|
|
534
|
+
- Without `paper_trail-association_tracking` loaded, asking for an
|
|
535
|
+
association between two versioned models raised `NoMethodError`. Reading
|
|
536
|
+
its history now raises `AssociationTrackingUnavailableError`, as
|
|
537
|
+
documented, and `association_paths` and a comparison of two current
|
|
538
|
+
records work again.
|
|
539
|
+
- On PostgreSQL, an association scope with a condition on a `character(n)`
|
|
540
|
+
column is no longer read as plain conditions. PostgreSQL pads such values
|
|
541
|
+
and compares them without the padding, which Ruby does not, so a member
|
|
542
|
+
could read as leaving and rejoining the association. It is now refused
|
|
543
|
+
unless you pass `allow_approximate: true`, as a `citext` condition is.
|
|
544
|
+
- A `within:` window whose first later version tied with another version
|
|
545
|
+
of the same record, with ids that cannot order them (such as UUIDs),
|
|
546
|
+
ended in whichever of the two had the lower id. Such a tie now raises
|
|
547
|
+
`AmbiguousVersionOrderError`, as one inside the window already did.
|
|
548
|
+
- `analyze_scope` and `report` raise `ConfigurationError` for a relation
|
|
549
|
+
grouped by anything but its primary key that has no order of its own,
|
|
550
|
+
instead of sending a query the database rejects.
|
|
551
|
+
- A `has_one` that two records point at, with no order of its own, now reads
|
|
552
|
+
the one with the lowest primary key at every point in history, as Active
|
|
553
|
+
Record reads it on SQLite, MySQL and SQL Server. History read another one,
|
|
554
|
+
so comparing the last version with the current record reported the
|
|
555
|
+
relationship changing when nothing had.
|
|
556
|
+
- A `within:` edge finer than a microsecond is cut to the microsecond, as
|
|
557
|
+
adapters write it into SQL. A version saved in the edge's microsecond was
|
|
558
|
+
in `timeline`'s window but not in `activity_timeline`'s or
|
|
559
|
+
`analyze_many`'s.
|
|
560
|
+
- A `within:` edge is cut to the digits the version table's `created_at`
|
|
561
|
+
keeps, as the database compares it. On a column that keeps whole seconds,
|
|
562
|
+
as a MySQL `datetime` without a precision does, an edge with a fraction
|
|
563
|
+
put a version saved in that second inside the window for one method and
|
|
564
|
+
outside it for another.
|
|
565
|
+
- With more than one version table, a `within:` window no longer reads an
|
|
566
|
+
unrelated transaction as one that crosses its edge. PaperTrail numbers a
|
|
567
|
+
transaction by the id of its first version in whichever table that was, so
|
|
568
|
+
two transactions can share a number in one table, and a window that started
|
|
569
|
+
or ended before the later one moved to where the earlier one began,
|
|
570
|
+
which could be years before: a window could take in changes from long
|
|
571
|
+
before it, or come back empty. `analyze_scope` selected records by the
|
|
572
|
+
earlier transaction too. Transactions of one number are now told apart
|
|
573
|
+
by the versions they began with.
|
|
574
|
+
- A transaction of associated records that moved a record away from the
|
|
575
|
+
root before a window's start, and after it saved only records under the
|
|
576
|
+
one it moved, was reported in neither window: `activity_timeline` and an
|
|
577
|
+
`activity: true` analysis left its changes out.
|
|
578
|
+
- A window that started inside a transaction which began at the instant
|
|
579
|
+
another saved its last versions, as it can where `created_at` keeps whole
|
|
580
|
+
seconds or two versions share a time, cut the earlier transaction in two,
|
|
581
|
+
and part of its change surfaced in the later transaction's step.
|
|
582
|
+
- A comment one transaction created and deleted again while another saved in
|
|
583
|
+
the same tree is no longer reported as added or removed in the other's
|
|
584
|
+
steps, nor held in a window's starting state or diff.
|
|
585
|
+
- Two activity windows that meet inside a transaction no longer both report
|
|
586
|
+
it when the transaction moved a `has_many :through` join row onto the
|
|
587
|
+
root and destroyed it after the edge, such as a card moved to a board and
|
|
588
|
+
destroyed while its assignee was renamed. The window after the edge judged
|
|
589
|
+
the join row by its destroy alone, where it was on the root, so the change
|
|
590
|
+
appeared in both halves. A join row's versions in one transaction are now
|
|
591
|
+
judged by the whole transaction, wherever a window's edge falls in it.
|
|
592
|
+
- A destroyed record read without `within:` ends at its last version,
|
|
593
|
+
instead of raising.
|
|
594
|
+
- A NaN stored on both sides no longer reads as a change, in attributes,
|
|
595
|
+
nested JSON, arrays and recorded changes.
|
|
596
|
+
- `recorded_changes: true` keeps a serialized hash's symbol keys, reads
|
|
597
|
+
versions of a custom class without `object_changes`, and leaves out a
|
|
598
|
+
change whose two sides are the same.
|
|
599
|
+
- `analyze_many` and `analyze_scope` read a root that stands in another
|
|
600
|
+
root's tree as `analyze` does when the roots are of two STI classes of one
|
|
601
|
+
table, and a windowed batch reads such a root at its state in the window,
|
|
602
|
+
not from its current row.
|
|
603
|
+
- A `belongs_to` naming an STI subclass reads no row of a sibling class, and
|
|
604
|
+
an `as:` child is a member only while its type is its owner's polymorphic
|
|
605
|
+
name, as Active Record reads them.
|
|
606
|
+
- A `has_many :through` with `source_type:` and a path below it descends only
|
|
607
|
+
into targets of that type, instead of raising for another type's.
|
|
608
|
+
- A `has_many :through` join row created and destroyed in one transaction is
|
|
609
|
+
no longer read as present, in another transaction's step or at the end of
|
|
610
|
+
a window.
|
|
611
|
+
- The end boundary of a window's last step no longer depends on which other
|
|
612
|
+
roots are in a batch.
|
|
613
|
+
|
|
6
614
|
## [0.17.1] - 2026-11-07
|
|
7
615
|
|
|
8
616
|
### Fixed
|
|
@@ -17,6 +625,46 @@ project follows [Semantic Versioning](https://semver.org/).
|
|
|
17
625
|
window's start, such as a comment moved to another parent and then saved
|
|
18
626
|
again or destroyed. The window before it leaves such a change to this
|
|
19
627
|
one, so a window split there no longer loses it from both halves.
|
|
628
|
+
- A serialized attribute that changed between values Ruby's `==` calls
|
|
629
|
+
equal, such as a Time to the matching string or `1` to `1.0`, alone or
|
|
630
|
+
nested, is reported as a change. Values must now be equal both ways, and a
|
|
631
|
+
Float differs from the Integer it equals.
|
|
632
|
+
- `recorded_changes` types an STI subclass's version with the subclass's
|
|
633
|
+
attribute types, as a step's states do, so an enum or a retyped column of
|
|
634
|
+
the subclass reads as its value.
|
|
635
|
+
- A relation passed to `analyze_scope`, `report` or `include_deleted:` is
|
|
636
|
+
read beside parts that choose no rows, such as `distinct`, `select`,
|
|
637
|
+
`order`, `unscope`, `rewhere`, `lock`, `annotate`, `preload` or
|
|
638
|
+
`create_with`, instead of being refused. Joins, `from`, `group`,
|
|
639
|
+
`having` and `with` are still refused.
|
|
640
|
+
- `include_deleted:` refuses a condition on a column `has_paper_trail skip:`
|
|
641
|
+
leaves out of history, as `historical_filter:` does, instead of comparing
|
|
642
|
+
it with the column's default; and, on SQLite, a `Date` bound on a datetime
|
|
643
|
+
column, which SQLite compares as text, instead of reading it as midnight.
|
|
644
|
+
- `historical_filter:` matches nothing for a value the attribute's type
|
|
645
|
+
cannot write, such as `''` or `'abc'` for an integer or one out of its
|
|
646
|
+
range, as `where` does.
|
|
647
|
+
- `historical_filter:`, with a hash or a callable, reads the live row as
|
|
648
|
+
history keeps it, so an unchanged value matches alike whether a version or
|
|
649
|
+
the live row closes the window, under JSON history too. A relation with
|
|
650
|
+
`limit(0)` selects nothing with a filter, as without one.
|
|
651
|
+
- A child made without a version, whose first version moved it to another
|
|
652
|
+
owner, is under the owner it left until then: PT-AT names only the owner a
|
|
653
|
+
version saved, so the one before is read from the first version's state.
|
|
654
|
+
- A `has_one :through` over a `has_one` reads every row of its parts, as its
|
|
655
|
+
one query joins them, rather than only the has_one's first row: a project
|
|
656
|
+
whose first pin has no user now has the user of the next, as Active Record
|
|
657
|
+
returns.
|
|
658
|
+
- A through's join row whose transaction changed nothing the tree shows,
|
|
659
|
+
such as a pin that names no user, or a member's own versions under a
|
|
660
|
+
through of a through before the member joined, is no longer a step of the
|
|
661
|
+
root. A member's versions under such a through are steps only where a
|
|
662
|
+
membership of the root named the member, and a record that is a join row
|
|
663
|
+
under one association is judged as any member under the others.
|
|
664
|
+
- `compare` between two versions of a record whose STI class changed
|
|
665
|
+
between them reads both from one history, so a change below the record in
|
|
666
|
+
between, such as a note moved to a member, is reported. It was read from
|
|
667
|
+
two histories, each beginning at its own version, and was missed.
|
|
20
668
|
|
|
21
669
|
## [0.17.0] - 2026-11-04
|
|
22
670
|
|