paper_trail_diff 0.16.0 → 0.17.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 +566 -1
- data/README.md +42 -7
- data/docs/architecture.md +7 -5
- data/docs/performance.md +86 -38
- data/docs/reference.md +309 -92
- data/docs/testing.md +240 -32
- data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
- data/lib/paper_trail_diff/activity_boundary.rb +55 -34
- data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
- data/lib/paper_trail_diff/activity_collection_event_applier.rb +3 -13
- data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
- data/lib/paper_trail_diff/activity_event.rb +33 -21
- data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
- data/lib/paper_trail_diff/activity_event_route_finder.rb +29 -29
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +2 -7
- data/lib/paper_trail_diff/activity_history.rb +90 -49
- data/lib/paper_trail_diff/activity_range.rb +9 -35
- data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +74 -40
- data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
- data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
- data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
- data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
- data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
- data/lib/paper_trail_diff/activity_timeline_builder.rb +194 -249
- data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
- data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
- data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
- data/lib/paper_trail_diff/activity_view.rb +22 -11
- data/lib/paper_trail_diff/analysis.rb +19 -5
- data/lib/paper_trail_diff/analysis_batch.rb +16 -58
- data/lib/paper_trail_diff/approximate_paths.rb +4 -8
- data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
- data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
- data/lib/paper_trail_diff/association_discovery.rb +1 -6
- data/lib/paper_trail_diff/association_key.rb +9 -6
- data/lib/paper_trail_diff/association_traversal.rb +49 -6
- data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
- data/lib/paper_trail_diff/batch_preload.rb +2 -12
- data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
- data/lib/paper_trail_diff/batched_root_analyzer.rb +16 -14
- data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
- data/lib/paper_trail_diff/branch_snapshot_refresher.rb +27 -31
- data/lib/paper_trail_diff/change_attribution.rb +314 -0
- data/lib/paper_trail_diff/change_row.rb +30 -10
- data/lib/paper_trail_diff/comparison_batch.rb +3 -4
- data/lib/paper_trail_diff/configuration.rb +1 -1
- data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -37
- data/lib/paper_trail_diff/deleted_root_filter.rb +3 -6
- data/lib/paper_trail_diff/deprecation.rb +4 -43
- data/lib/paper_trail_diff/diagnostics.rb +1 -2
- data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
- data/lib/paper_trail_diff/endpoint.rb +78 -44
- data/lib/paper_trail_diff/errors.rb +2 -9
- data/lib/paper_trail_diff/fallback_paths.rb +2 -5
- data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
- data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
- data/lib/paper_trail_diff/historical_filter.rb +40 -15
- data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
- data/lib/paper_trail_diff/instrumentation.rb +0 -8
- data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
- data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
- data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
- data/lib/paper_trail_diff/nested_comparator.rb +46 -19
- data/lib/paper_trail_diff/net_change.rb +276 -0
- data/lib/paper_trail_diff/own_window.rb +35 -0
- data/lib/paper_trail_diff/paper_trail_adapter.rb +40 -45
- data/lib/paper_trail_diff/prepared_activity_index.rb +170 -42
- data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
- data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
- data/lib/paper_trail_diff/prepared_history.rb +20 -31
- data/lib/paper_trail_diff/prepared_history_loader.rb +46 -9
- data/lib/paper_trail_diff/prepared_record_index.rb +137 -47
- data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
- data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
- data/lib/paper_trail_diff/read_snapshot.rb +41 -19
- data/lib/paper_trail_diff/recorded_changes.rb +10 -11
- data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
- data/lib/paper_trail_diff/recorded_class.rb +14 -19
- data/lib/paper_trail_diff/recorded_columns.rb +33 -0
- data/lib/paper_trail_diff/root_version_plan.rb +20 -22
- data/lib/paper_trail_diff/root_version_selection.rb +39 -29
- data/lib/paper_trail_diff/scope_condition.rb +7 -17
- data/lib/paper_trail_diff/scope_ranking.rb +16 -22
- data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
- data/lib/paper_trail_diff/scoped_root_selection.rb +60 -41
- data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
- data/lib/paper_trail_diff/stored_json_values.rb +52 -0
- data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
- data/lib/paper_trail_diff/stored_values.rb +20 -0
- data/lib/paper_trail_diff/support.rb +185 -35
- data/lib/paper_trail_diff/time_of_day.rb +39 -0
- data/lib/paper_trail_diff/time_range.rb +37 -20
- data/lib/paper_trail_diff/time_version_range.rb +5 -10
- data/lib/paper_trail_diff/timeline_builder.rb +3 -3
- data/lib/paper_trail_diff/timeline_range.rb +18 -12
- data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
- data/lib/paper_trail_diff/total_order.rb +55 -0
- data/lib/paper_trail_diff/transaction_cut.rb +192 -91
- data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
- data/lib/paper_trail_diff/value_objects.rb +8 -4
- data/lib/paper_trail_diff/version.rb +1 -1
- data/lib/paper_trail_diff/version_association_candidate_scope.rb +1 -12
- data/lib/paper_trail_diff/version_boundary.rb +37 -21
- data/lib/paper_trail_diff/version_query.rb +25 -25
- data/lib/paper_trail_diff/version_range.rb +12 -16
- data/lib/paper_trail_diff/version_sequence_diagnostics.rb +32 -0
- data/lib/paper_trail_diff/version_table.rb +12 -8
- data/lib/paper_trail_diff.rb +28 -42
- data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
- data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
- data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
- data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +0 -5
- data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
- data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
- data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +11 -4
- data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +0 -3
- data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
- data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
- data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +36 -2
- data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
- data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
- data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
- data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
- data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
- data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +121 -127
- data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
- data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
- data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
- data/sig/generated/paper_trail_diff/analysis.rbs +15 -6
- data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
- data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
- data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
- data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
- data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
- data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
- data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
- data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
- data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
- data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -8
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
- data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +11 -5
- data/sig/generated/paper_trail_diff/change_attribution.rbs +185 -0
- data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
- data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -12
- data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +0 -2
- data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
- data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
- data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
- data/sig/generated/paper_trail_diff/errors.rbs +2 -11
- data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
- data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
- data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
- data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
- data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
- data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
- data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
- data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
- data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
- data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
- data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +9 -6
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +103 -14
- data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
- data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
- data/sig/generated/paper_trail_diff/prepared_history.rbs +9 -12
- data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +68 -14
- data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
- data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
- data/sig/generated/paper_trail_diff/read_snapshot.rbs +27 -8
- data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
- data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
- data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
- data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
- data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
- data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
- data/sig/generated/paper_trail_diff/scope_condition.rbs +0 -2
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -10
- data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +37 -14
- data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
- data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
- data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
- data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
- data/sig/generated/paper_trail_diff/support.rbs +120 -23
- data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
- data/sig/generated/paper_trail_diff/time_range.rbs +15 -8
- data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
- data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
- data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
- data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
- data/sig/generated/paper_trail_diff/transaction_cut.rbs +111 -52
- data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
- data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
- data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +0 -7
- data/sig/generated/paper_trail_diff/version_boundary.rbs +15 -8
- data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
- data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
- data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +13 -0
- data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
- data/sig/generated/paper_trail_diff.rbs +16 -16
- metadata +28 -6
- data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
- data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 65edaa0075d29690f71577182beeee2e829c635726e398e940c98afe78673b87
|
|
4
|
+
data.tar.gz: 4f836ce363c5144ec2c6379ad94be8c5320d17bb07615a4dd7ca535d78143c00
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 69752b123cbedd21a70619017c9573ae9c9cda176a6eddab74021b4cf67bc5d10671d7eb9665ec158f339ae1dba13ae5e63d3122574f21a0323fff1202ef8f3a
|
|
7
|
+
data.tar.gz: 45a1be2bd8f564afde3f459b3d793d5d08b4c6827a271912894eed90e85f631db95b0b0c3739fae67a16e49d92b20af5a5794fc2817c2f6d5b2f3b8745db0e84
|
data/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,571 @@
|
|
|
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.17.0] - 2026-11-04
|
|
7
|
+
|
|
8
|
+
### Breaking changes
|
|
9
|
+
|
|
10
|
+
- The options deprecated in 0.15.0 are removed, and passing one raises
|
|
11
|
+
`ArgumentError` (unknown keyword):
|
|
12
|
+
- `close_on:` on `timeline`, `activity_timeline`, `analyze`, `analyze_many`,
|
|
13
|
+
and `analyze_scope`. It had no effect: a window already closes on the
|
|
14
|
+
current record when nothing on its requested paths was recorded after it.
|
|
15
|
+
- `allow_expensive:` on `compare_many`, `analyze_many`, `analyze_scope`, and
|
|
16
|
+
`report`. It had no effect: `allow_approximate: true` alone accepts a path
|
|
17
|
+
read with PT-AT.
|
|
18
|
+
- `reload_live_endpoints:` on `compare`, `compare_many`, and
|
|
19
|
+
`activity_timeline`. Every method now reloads the current records it
|
|
20
|
+
compares with, as it did by default.
|
|
21
|
+
- `UnloadedAssociationError`, which only `reload_live_endpoints: false` raised,
|
|
22
|
+
and `UnsupportedBatchPathError`, which nothing raised since 0.15.0, are
|
|
23
|
+
removed. Code that rescues either must stop naming it.
|
|
24
|
+
- The `compare.paper_trail_diff`, `compare_many.paper_trail_diff`, and
|
|
25
|
+
`load_live_endpoints.paper_trail_diff` payloads no longer have a
|
|
26
|
+
`reload_live_endpoints` key.
|
|
27
|
+
- `version_scope:` applies to the versions of the requested associations as
|
|
28
|
+
it does to the root's own:
|
|
29
|
+
- In `analyze_scope` and `report`, a change on a requested association
|
|
30
|
+
selects a record only when the filter keeps its version. A record that
|
|
31
|
+
only versions the filter leaves out changed is no longer selected, and no
|
|
32
|
+
longer counts toward `limit:`.
|
|
33
|
+
- In activity (`activity_timeline`, `activity: true`, and `report`), the
|
|
34
|
+
filter decides which steps are reported: every step of a transaction in
|
|
35
|
+
which it keeps a version, of any record, and each version saved outside a
|
|
36
|
+
transaction that it keeps. Activity listed every step between the first
|
|
37
|
+
and the last root version the filter kept, whoever made it, and every
|
|
38
|
+
change on an association. Every version is still replayed, so each step
|
|
39
|
+
shows what its own change did. An analysis starts at the first change the
|
|
40
|
+
filter keeps, on the record or its associations, and ends after the last.
|
|
41
|
+
- Without associations, activity reports the root's versions the filter
|
|
42
|
+
keeps, as `timeline` does.
|
|
43
|
+
|
|
44
|
+
The record and its associations keep their versions in one table, which
|
|
45
|
+
the filter reads for all of them, so a condition on `item_type` or
|
|
46
|
+
`item_id` now leaves out the associations' changes. A filter that keeps
|
|
47
|
+
every version now reads as no filter: a range of one version, which no
|
|
48
|
+
later version reveals, has that version's state rather than none.
|
|
49
|
+
|
|
50
|
+
### Added
|
|
51
|
+
|
|
52
|
+
- With `recorded_changes: true`, change rows tell a write saved without a
|
|
53
|
+
version, such as `update_columns`, apart from the change it follows.
|
|
54
|
+
PaperTrail reads such a write into the record's next version, or its
|
|
55
|
+
current row, so it shows up in the step of the record's previous change,
|
|
56
|
+
and its row was credited to that change's author. The part of a change no
|
|
57
|
+
version recorded now has a row of its own, whose `source` has kind
|
|
58
|
+
`:unversioned`, names the record, and has no version, event, author, or
|
|
59
|
+
time; `ChangeRow#unversioned?` and `ActivityBoundary#unversioned?` tell
|
|
60
|
+
them apart. A field a version recorded changing from 10 to 20, which an
|
|
61
|
+
`update_columns` then set to 99, gives two rows: 10 to 20, credited to the
|
|
62
|
+
version, and 20 to 99, unversioned. A write between two of a record's
|
|
63
|
+
versions in one transaction, which no step shows on its own, is split off
|
|
64
|
+
the same way. A row stays whole, credited to a version, where history
|
|
65
|
+
cannot show the write was unrecorded: a version that recorded no changes,
|
|
66
|
+
such as a `touch`; a column `has_paper_trail` leaves out of
|
|
67
|
+
`object_changes`; a field a create left at its default; and the start of a
|
|
68
|
+
transaction that began before a window and saved no version of the root.
|
|
69
|
+
The [change rows](docs/reference.md#change-rows) reference lists them.
|
|
70
|
+
|
|
71
|
+
- `Analysis#net_changes` and `ScopedAnalysis#net_changes` fold an activity's
|
|
72
|
+
change rows into one `NetChange` for each record: its fields before the
|
|
73
|
+
rows a block keeps, its fields with only those changes made, and the
|
|
74
|
+
difference. Keeping the rows that name an author reports what people
|
|
75
|
+
changed, and with `recorded_changes: true` leaves out writes saved without
|
|
76
|
+
a version: `report.net_changes { |row| row.source.whodunnit }`. The root
|
|
77
|
+
comes first whenever anything changed. The states come from the steps'
|
|
78
|
+
snapshots, so it needs `snapshots: true`. See
|
|
79
|
+
[net changes](docs/reference.md#net-changes).
|
|
80
|
+
|
|
81
|
+
- `ScopedAnalysis#analysis_for(record)` returns the analysis of one of
|
|
82
|
+
`roots`, the records `analyze_scope` and `report` load, without building
|
|
83
|
+
its key: the base class's name and the ID as a string, which a subclass or
|
|
84
|
+
an integer ID gets wrong when built by hand.
|
|
85
|
+
|
|
86
|
+
- `within:` accepts an endless range, such as `1.day.ago..`, which runs
|
|
87
|
+
through the current saved state, as `report` does.
|
|
88
|
+
|
|
89
|
+
- `diagnose` warns with `inverted_version_order` when a record's versions are
|
|
90
|
+
dated in another order than their IDs show they were saved in. PaperTrail
|
|
91
|
+
dates an update with the record's `updated_at` unless `has_paper_trail
|
|
92
|
+
synchronize_version_creation_timestamp: false`, so a save that set
|
|
93
|
+
`updated_at` itself, such as an import keeping another system's times, a
|
|
94
|
+
`touch(time:)`, or one made with timestamps off, can date its version in
|
|
95
|
+
the past. History is read in time order, so such an update is read before
|
|
96
|
+
the change it followed, and one dated before the record's `create` reads as
|
|
97
|
+
the record deleted and created again. The
|
|
98
|
+
[version order](docs/reference.md#version-order) section explains the fix.
|
|
99
|
+
|
|
100
|
+
- On SQL Server, each call reads its history and live rows in one `SNAPSHOT`
|
|
101
|
+
transaction when the database allows snapshot isolation
|
|
102
|
+
(`ALTER DATABASE ... SET ALLOW_SNAPSHOT_ISOLATION ON`), as it does at
|
|
103
|
+
`REPEATABLE READ` on PostgreSQL and MySQL. A commit that lands during the
|
|
104
|
+
call is then seen by none of its statements. Each call checks the setting
|
|
105
|
+
first, in one statement; without it, nothing changes.
|
|
106
|
+
|
|
107
|
+
### Changed
|
|
108
|
+
|
|
109
|
+
- A change row names the version of its own record that made the change.
|
|
110
|
+
It named its step's source boundary: for a transaction group, the
|
|
111
|
+
transaction's first event, whichever record that was; and without
|
|
112
|
+
grouping, a child's change that showed up at a later event of its
|
|
113
|
+
transaction, in a step another record's version opens, named that version.
|
|
114
|
+
A record created or destroyed names its create or destroy, and its fields
|
|
115
|
+
the version that recorded each value. A record that joined or left through
|
|
116
|
+
another record's change, such as a new `belongs_to` target, still names the
|
|
117
|
+
step's source boundary.
|
|
118
|
+
Without `recorded_changes: true` the gem cannot tell which of a record's
|
|
119
|
+
versions in a transaction made a change, and names the last of them.
|
|
120
|
+
|
|
121
|
+
- `recorded_changes`, and each activity boundary's `recorded_changes`, read
|
|
122
|
+
values as a step's diff reads them, so a recorded value equals the state it
|
|
123
|
+
produced: a time of day on 2000-01-01, and with JSON history, times to the
|
|
124
|
+
digits history stores and binary and `serialize`d values as JSON stored
|
|
125
|
+
them.
|
|
126
|
+
|
|
127
|
+
- `report` reads every version saved since `since:`, with no end. Its window
|
|
128
|
+
ended at the time of the call, so a version a server whose clock ran ahead
|
|
129
|
+
of the reporting server's had dated a moment later was left out, and the
|
|
130
|
+
report ended before a change the current record already held. It no longer
|
|
131
|
+
looks for transactions that cross that end, or for each record's first
|
|
132
|
+
version after it, which saves up to three statements per 500 records.
|
|
133
|
+
`analysis.window` is endless (`since..`) for a report, and a `since:` in the
|
|
134
|
+
future gives an empty report rather than raising `InvalidTimeRangeError`,
|
|
135
|
+
whose message named `within:`.
|
|
136
|
+
|
|
137
|
+
- The README said change rows leave out the blank fields of a record that
|
|
138
|
+
appeared or disappeared. Only `nil` fields are left out: an empty string or
|
|
139
|
+
`false` gets a row.
|
|
140
|
+
|
|
141
|
+
- The performance guide's query counts were measured again, and it compares
|
|
142
|
+
PaperTrail's JSON serializer with its default YAML one: a report read JSON
|
|
143
|
+
in about 40% less time. It also says what `historical_filter:` costs on SQL
|
|
144
|
+
Server, where each page of matching records lists every matching id. The
|
|
145
|
+
architecture guide no longer says a window's transaction lookups take four
|
|
146
|
+
per root, sent 200 roots per query.
|
|
147
|
+
|
|
148
|
+
- The reference says what happens when two transactions save in the same
|
|
149
|
+
tree at the same time, so that their versions interleave: each forms more
|
|
150
|
+
than one group with `group: :transaction`, and a record one of them changed
|
|
151
|
+
and changed back can appear in the other's steps, and in a window's
|
|
152
|
+
starting state and diff.
|
|
153
|
+
|
|
154
|
+
- `analyze_many`, `analyze_scope`, `report`, and `compare_many` list at most
|
|
155
|
+
500 ids in a statement, as the rest of the gem does. Reading the batch's
|
|
156
|
+
versions, the transactions its first versions belong to, its associations'
|
|
157
|
+
candidates and rows, its deleted records' destroys, and its current rows
|
|
158
|
+
and their associations each listed every record of the batch at once. On
|
|
159
|
+
SQL Server, which writes such a list into the statement and compiles it
|
|
160
|
+
afresh, a `report` of 10,000 articles and their comments took 17.1 s and
|
|
161
|
+
now takes 11.4 s, and one of 20,000 took 38.9 s and now takes 23.0 s; a
|
|
162
|
+
statement listing 20,000 transactions alone failed with error 8623. With
|
|
163
|
+
`historical_filter:`, or a version table whose `item_id` does not share the
|
|
164
|
+
key's type, the records are read among a list of ids, which each page of
|
|
165
|
+
250 repeated: they are now read in pages of one past `limit:`, up to 2,000.
|
|
166
|
+
On SQL Server, such a report of 10,000 articles took 47.4 s and now takes
|
|
167
|
+
14.4 s, and one of 20,000 took 280.5 s and now takes 51.1 s.
|
|
168
|
+
|
|
169
|
+
- `analyze_scope` and `report` read the records a relation selects in pages
|
|
170
|
+
of one past `limit:`, at least 250 and at most 2,000 records, rather than
|
|
171
|
+
250. Each page runs again the subqueries that find which records changed
|
|
172
|
+
and skips the rows before it, so a selection of 10,000 articles changed in
|
|
173
|
+
the window, with their comments, took 1.5 s on SQLite and now takes 0.3 s.
|
|
174
|
+
|
|
175
|
+
- `historical_filter:` reads its candidates' versions, and selecting a record
|
|
176
|
+
by a change on its associations reads ids, 500 to a statement rather than
|
|
177
|
+
250, as the rest of the gem does.
|
|
178
|
+
|
|
179
|
+
- Activity on associations decodes each of the record's versions once for
|
|
180
|
+
the call. It decoded a version again at every event the version bounded,
|
|
181
|
+
up to five times: a `report` of 10,000 articles with their comments took
|
|
182
|
+
about 20 s on SQLite and now takes about 18 s, and peaks at about 100 MB
|
|
183
|
+
less memory.
|
|
184
|
+
|
|
185
|
+
- History on a `has_and_belongs_to_many` groups the members PT-AT recorded
|
|
186
|
+
by transaction once. Each of the root's transactions looked through every
|
|
187
|
+
member recorded for all of them, so the cost grew with the square of the
|
|
188
|
+
root's versions: a `timeline` of an article with 2,000 versions and its
|
|
189
|
+
tags took 9.2 s and now takes 1.9 s, and an `analyze_many` of 200 tagged
|
|
190
|
+
articles with 20 versions each took 34.6 s and now takes 4.0 s. The
|
|
191
|
+
members and the transactions' owners are read 500 transactions per
|
|
192
|
+
statement, as other lists of ids are: on SQL Server, a statement listing
|
|
193
|
+
40,000 ids timed out.
|
|
194
|
+
|
|
195
|
+
- With `version_scope:`, `timeline`, `analyze`, and the batch methods find
|
|
196
|
+
the version after each one the filter keeps with a search. They passed
|
|
197
|
+
every version in range before it, so the cost grew with the square of the
|
|
198
|
+
record's versions: a `timeline` of an article with 4,000 versions, half of
|
|
199
|
+
them kept, took 9.5 s and now takes 1.4 s, about as long as without the
|
|
200
|
+
filter.
|
|
201
|
+
|
|
202
|
+
- Preparing history no longer checks each record against every one before
|
|
203
|
+
it in two lists: the targets of a polymorphic `belongs_to`, and the owners
|
|
204
|
+
of an association requested both alone and as the first part of a
|
|
205
|
+
`has_many :through`. Each check cost little, about 0.1 s in an
|
|
206
|
+
`analyze_many` of 3,000 authors with their articles and the comments
|
|
207
|
+
through them, but the total grew with the square of the batch.
|
|
208
|
+
|
|
209
|
+
- Snapshots of a record with its associations do less work at each version
|
|
210
|
+
of the record, with the same results. Each member's version times and its
|
|
211
|
+
scope's condition are read once rather than at every version, a member
|
|
212
|
+
that did not change is normalized once, and a snapshot that starts from
|
|
213
|
+
the current record reads its associations from prepared history, as one
|
|
214
|
+
that starts from a version does, rather than building each member as an
|
|
215
|
+
Active Record record. A `timeline` of an article with 2,001 versions and
|
|
216
|
+
300 comments took 14.9 s and now takes 7.5 s, and an `analyze_scope` with
|
|
217
|
+
activity over a day's changes to 373 articles, with their comments,
|
|
218
|
+
replies, reviewers, and authors, took 4.3 s and now takes 3.9 s.
|
|
219
|
+
|
|
220
|
+
- With `recorded_changes: true`, a boundary decodes its version's changes the
|
|
221
|
+
first time its `recorded_changes` is read, and each version is decoded once
|
|
222
|
+
for the whole call. Every boundary decoded its version when it was built,
|
|
223
|
+
so a version that many records share in a batch, such as an author's, was
|
|
224
|
+
decoded once for each of them, and a step nobody read cost as much as one
|
|
225
|
+
that was. A decoding error now raises when the changes are read.
|
|
226
|
+
|
|
227
|
+
- Activity asks Active Record whether a value is a version or a record once
|
|
228
|
+
for each model class, rather than on every read: Active Record answers
|
|
229
|
+
`respond_to?` by also looking through the record's attributes. An
|
|
230
|
+
`analyze_many` of 2,000 articles with their comments took about 9% less
|
|
231
|
+
time.
|
|
232
|
+
|
|
233
|
+
- `analyze_many`, `analyze_scope`, and `report` with `activity: true` read
|
|
234
|
+
the association history of a record that has no version in the window,
|
|
235
|
+
but whose associated records changed there, together with the rest of the
|
|
236
|
+
batch. Such a record, as in a `report(since:)` of articles that only gained
|
|
237
|
+
comments, read its own history, at about nine statements each. A batch of
|
|
238
|
+
20 such articles took 188 statements and now takes 14, as many as one.
|
|
239
|
+
|
|
240
|
+
- Activity on a `has_many` or `has_one` reads the children each owner had
|
|
241
|
+
once. Preparing the history read them for its snapshots, and finding the
|
|
242
|
+
activity read them again: an `analyze_many` of three articles with their
|
|
243
|
+
comments took 16 statements and now takes 14.
|
|
244
|
+
|
|
245
|
+
- `analyze` and `activity_timeline` with activity on associations read the
|
|
246
|
+
current record's row once for the snapshots that start from it, as
|
|
247
|
+
`analyze_many` already did. Each such snapshot read the row again: after
|
|
248
|
+
four transactions that changed two comments each, an article's activity
|
|
249
|
+
read its row ten times rather than four.
|
|
250
|
+
|
|
251
|
+
- On SQL Server, a window's transaction-edge lookup sends its record ids as
|
|
252
|
+
bound parameters, as the other id lists do, instead of writing them into
|
|
253
|
+
each statement. SQL Server compiled each such statement afresh, at about
|
|
254
|
+
0.05 ms per id. On 10,000 roots, the lookup's SQL time fell from 1.4 s to
|
|
255
|
+
0.7 s and a report from 5.1 s to 4.4 s, with the same windows. The lookup
|
|
256
|
+
now names 250 ids a statement rather than 500, since each id appears twice
|
|
257
|
+
in it: 1,000 ids a statement was slower, and would exceed the 999 bound
|
|
258
|
+
parameters SQLite allowed before 3.32.
|
|
259
|
+
|
|
260
|
+
- Activity reads the state of a transaction that saved its root together
|
|
261
|
+
with descendants once for that transaction's descendant events, not again
|
|
262
|
+
at each one. PT-AT reads what a transaction saved as it stood before the
|
|
263
|
+
transaction began, so from one descendant's event to the next in the same
|
|
264
|
+
transaction the snapshot is the same; it was rebuilt whole each time. A
|
|
265
|
+
`report` on 100 articles, each created with 100 comments in one transaction
|
|
266
|
+
and edited with all of them in another, took 20.1 s and now takes 4.6 s,
|
|
267
|
+
and allocated a quarter as many objects. On 10,000 articles at about 1.5
|
|
268
|
+
versions each with their comments, it took 14.6 s and now takes 13.9 s.
|
|
269
|
+
The results are the same.
|
|
270
|
+
|
|
271
|
+
- Activity carries the snapshot at a root's version to the next event by
|
|
272
|
+
comparing the root's state at the two, which the snapshots decode anyway.
|
|
273
|
+
It decoded the version's recorded changes and the state after it a second
|
|
274
|
+
time instead, which took longer than rebuilding the snapshot whole. The
|
|
275
|
+
next descendant's event in the same transaction as a root's update is now
|
|
276
|
+
carried forward the same way, where it was rebuilt whole. A `report` on
|
|
277
|
+
2,000 articles with about 1.5 comments each, each article edited ten
|
|
278
|
+
times and about a fifth of those edits saved with a comment, took 19.9 s
|
|
279
|
+
and now takes 14.8 s, with a fifth fewer allocations. The results are the
|
|
280
|
+
same.
|
|
281
|
+
|
|
282
|
+
- A batch reads its requested associations' reflections once for the whole
|
|
283
|
+
call, where each root's activity resolved and checked them again, and it
|
|
284
|
+
reads a current record's attributes for its history only when a read
|
|
285
|
+
reaches past that record's last version. Most do not: in a `report` on
|
|
286
|
+
10,000 articles with their comments, about a quarter of the 25,000 current
|
|
287
|
+
records were read that way. The snapshots that start from a root's current
|
|
288
|
+
row also share one reading of it, from the record the call loaded. That
|
|
289
|
+
report takes about 7% less time and allocates 8% fewer objects; one on
|
|
290
|
+
2,000 articles edited ten times each, and one on 100 articles with 100
|
|
291
|
+
comments each, about 3% less time. The results are the same.
|
|
292
|
+
|
|
293
|
+
### Fixed
|
|
294
|
+
|
|
295
|
+
- `nested_changes` treats `:a` and `"a"` as one key inside arrays too, as it
|
|
296
|
+
already did in objects. An array whose objects differed only in key type,
|
|
297
|
+
such as a hash built in Ruby against one read back from JSON, was reported
|
|
298
|
+
as having lost one element and gained another. Elements are still reported
|
|
299
|
+
as they were given, and `{ a: 1, "a" => 2 }` inside an array now raises
|
|
300
|
+
`AmbiguousNestedKeyError`, as it does in an object.
|
|
301
|
+
|
|
302
|
+
- With `historical_filter:`, `analyze_scope` and `report` test each record over
|
|
303
|
+
the window its analysis covers. A transaction that crosses the window's
|
|
304
|
+
start or end moves that window to where the transaction began, but the
|
|
305
|
+
filter read the window as asked: it missed a value the record held at the
|
|
306
|
+
moved start, such as its title before the transaction changed it, and
|
|
307
|
+
matched one held only past a moved end.
|
|
308
|
+
|
|
309
|
+
- `analyze_scope` and `report` no longer lose a record's change when a
|
|
310
|
+
window's edge falls inside a transaction that saved the record before the
|
|
311
|
+
edge and another article, or a record off the requested paths, after it.
|
|
312
|
+
The record's window moved to the later window, which did not select it,
|
|
313
|
+
while the earlier window left the change out: an update, or a deletion with
|
|
314
|
+
`include_deleted: true`, was in neither report. Such a transaction now moves
|
|
315
|
+
no edge, so the change is in the earlier window, with the record's version.
|
|
316
|
+
When the transaction saved a record on the requested paths after the edge,
|
|
317
|
+
the edge still moves, and `analyze_scope` and `report` now select the record
|
|
318
|
+
in the later window with or without `activity: true`.
|
|
319
|
+
|
|
320
|
+
- Activity over a window (`activity: true`, `activity_timeline`, and
|
|
321
|
+
`report`) no longer raises `KeyError` when a record on one requested path,
|
|
322
|
+
such as an author, is also a `belongs_to` target on another path with
|
|
323
|
+
associations requested below it
|
|
324
|
+
(`["author", "comments.reviewer.reviewed_comments"]`). A target named only
|
|
325
|
+
by a version saved after the window was followed as if its own associations
|
|
326
|
+
had been read, and they had not been.
|
|
327
|
+
|
|
328
|
+
- With `historical_filter:`, `analyze_scope` and `report` accept a relation
|
|
329
|
+
grouped by anything but the ID, such as each author's latest article
|
|
330
|
+
(`select("MAX(id) AS id").group(:author_id)`), and select the records it
|
|
331
|
+
groups among those that match. Before filtering, they asked the relation
|
|
332
|
+
for the IDs among each 250 candidates, which reads a group's column
|
|
333
|
+
instead of its aggregate: PostgreSQL, MySQL, and SQL Server rejected the
|
|
334
|
+
query, and SQLite returned any record of each group.
|
|
335
|
+
|
|
336
|
+
- History stored as JSON no longer reports two kinds of value as changed in
|
|
337
|
+
every comparison with the current record, though nothing changed them. A
|
|
338
|
+
`json` or `jsonb` `object` column stores a `serialize`d attribute as JSON
|
|
339
|
+
writes it, so a `Date` or `Symbol` inside it came back as a String: that
|
|
340
|
+
attribute is now read as JSON writes it on every side, the current
|
|
341
|
+
record's included. PaperTrail's JSON serializer stores a `binary` column
|
|
342
|
+
as `{ "value" => bytes }`, which is now read as the bytes.
|
|
343
|
+
|
|
344
|
+
- Without associations, activity (`activity_timeline`, `activity: true`, and
|
|
345
|
+
`report`) reports a change saved without a version, such as one by
|
|
346
|
+
`update_columns` or with versioning off, in the step for the record's
|
|
347
|
+
previous recorded change, as `timeline` and activity on associations do.
|
|
348
|
+
It was reported in the step for the record's next version, and so credited
|
|
349
|
+
to that version's author: a title written by `update_columns` after
|
|
350
|
+
Alice's edit was reported as part of Mallory's next edit.
|
|
351
|
+
|
|
352
|
+
- `analyze_scope` and `report` read every record a relation selects when its
|
|
353
|
+
order has ties, such as `Article.order(:status)`, and more than 250 records
|
|
354
|
+
match. Records were read 250 at a time in that order, and PostgreSQL and
|
|
355
|
+
MySQL may return rows that tie in a different order for each query, so some
|
|
356
|
+
records were read twice and others never, without an error: of 2,000
|
|
357
|
+
changed articles ordered by status, PostgreSQL selected 1,606. The ID now
|
|
358
|
+
ends any order that does not already sort by it. SQL text counts as sorting
|
|
359
|
+
by the ID when it names the column, alone or after the table's name. The
|
|
360
|
+
order of a relation grouped by anything but the ID is kept as given, since
|
|
361
|
+
a database sorts groups only by what they group or aggregate.
|
|
362
|
+
|
|
363
|
+
- With PaperTrail's default YAML serializer, a `time` column reads as the
|
|
364
|
+
time each version recorded. PaperTrail 16 and 17 decode such a value as
|
|
365
|
+
`nil`, unless the column is time-zone aware and the time zone is UTC, and
|
|
366
|
+
so did the gem, so the step that set a time showed no change, every
|
|
367
|
+
comparison of a later version with the current record showed the time
|
|
368
|
+
changing from `nil`, and `recorded_changes` reported
|
|
369
|
+
`{ from: nil, to: nil }`. That includes records the gem rebuilds with
|
|
370
|
+
PaperTrail's `reify`: models with initialization callbacks, custom types or
|
|
371
|
+
defaults, default scopes that assign attributes, or encrypted attributes;
|
|
372
|
+
a version that holds a column the model no longer has; the records a
|
|
373
|
+
callable `historical_filter:` receives; and association members PT-AT
|
|
374
|
+
rebuilds. Each such record's time is assigned from its own version, which
|
|
375
|
+
is decoded a second time only when it holds a time of day. A time is read
|
|
376
|
+
on 2000-01-01, as the row keeps it: a column that is not time-zone aware
|
|
377
|
+
keeps in memory the date of the time assigned to it, such as
|
|
378
|
+
`Time.current`'s, and the versions saved from that record store it. Before
|
|
379
|
+
Active Record 8.1, a zone-aware time read from the database falls on
|
|
380
|
+
2000-01-01 in UTC, and one assigned on 2000-01-01 in the time zone, so
|
|
381
|
+
every time of day is compared on 2000-01-01 in its own zone, as Active
|
|
382
|
+
Record 8.1 reads both.
|
|
383
|
+
|
|
384
|
+
- `analyze_scope` and `report` accept a relation whose `limit` or `offset` is
|
|
385
|
+
a String, as request parameters are, such as
|
|
386
|
+
`Article.offset(params[:offset])`. A String offset raised `TypeError`, and
|
|
387
|
+
before Active Record 8.1, which casts a limit as it is set, a String limit
|
|
388
|
+
raised `NoMethodError`. A String `limit` or `offset` in an association's
|
|
389
|
+
scope is read from history as an Integer one is: before 8.1 a String limit
|
|
390
|
+
raised `TypeError` there, and a String offset made the association one that
|
|
391
|
+
only `allow_approximate: true` reads.
|
|
392
|
+
|
|
393
|
+
- Activity from a version reports a record that left one of the requested
|
|
394
|
+
associations earlier in that version's transaction, such as a comment
|
|
395
|
+
moved to another article or destroyed just before the article's version
|
|
396
|
+
was saved. The range starts from the state before the transaction, which
|
|
397
|
+
holds the record, but the record's own versions were not read, so its
|
|
398
|
+
removal was left out, or reported in the next step that read the
|
|
399
|
+
association again, under that step's transaction and author.
|
|
400
|
+
|
|
401
|
+
- Activity on a `has_many :through` leaves out the versions a join record
|
|
402
|
+
saved while it joined another record, judged by transaction as any record
|
|
403
|
+
is: by whether it joined the owner before the transaction or after it. A
|
|
404
|
+
card created on one board and moved to another later brought every version
|
|
405
|
+
it saved on the first board into the second board's activity, and so did a
|
|
406
|
+
card created and destroyed inside one transaction: each was a step of its
|
|
407
|
+
own, and a transaction group listed it in `sources`. Inside a transaction,
|
|
408
|
+
where a change surfaces one event late, such a step also took the credit
|
|
409
|
+
for the change made just before it, under its own author.
|
|
410
|
+
|
|
411
|
+
- A window in which every event was of a record outside the requested
|
|
412
|
+
associations throughout, such as a comment past a scope's `limit` or one
|
|
413
|
+
its default scope leaves out, reports nothing. With nothing recorded after
|
|
414
|
+
it, such a window had a step whose `sources` held `nil` and that showed the
|
|
415
|
+
record as created. With something recorded after it, the analysis was empty
|
|
416
|
+
but still held both snapshots; both are `nil` now, as for any analysis that
|
|
417
|
+
reports nothing.
|
|
418
|
+
|
|
419
|
+
- Back-to-back windows, or a `report` with `since:` after an earlier report,
|
|
420
|
+
that meet inside a transaction that saved associated records on both sides
|
|
421
|
+
of the edge, and no version of the root, report the changes it saved before
|
|
422
|
+
the edge. Neither window reported them: the earlier one ended at the state
|
|
423
|
+
before the transaction, as any window ending inside one does, and the later
|
|
424
|
+
one started after them, and did not know a record the transaction
|
|
425
|
+
destroyed before the edge. Now all of the transaction's changes are
|
|
426
|
+
reported once: in the later window, which starts from the state before the
|
|
427
|
+
transaction, when a version it saved after the edge is of a record on the
|
|
428
|
+
requested paths, and otherwise in the earlier window. A transaction group
|
|
429
|
+
lists in `sources` only the versions inside its window. Finding such
|
|
430
|
+
transactions takes one statement per 500 of the transactions a window's
|
|
431
|
+
history reads; when it finds one, the window's history is read again from
|
|
432
|
+
where that transaction began.
|
|
433
|
+
|
|
434
|
+
- A window whose last change a `version_scope:` keeps is followed by the
|
|
435
|
+
version that shows what that change did, and that version now comes after
|
|
436
|
+
the window as well. Activity reported no step for the change, and
|
|
437
|
+
`analyze_many` with associations read the associations' state at that
|
|
438
|
+
version from history that ended with the window: a comment edited again
|
|
439
|
+
after it showed its latest body instead of the one it had then.
|
|
440
|
+
|
|
441
|
+
- `analyze_many` with `activity: true`, associations, and a `version_scope:`
|
|
442
|
+
that keeps none of a record's versions reports nothing for that record over
|
|
443
|
+
its whole history, as `analyze` does. It raised `IncompleteTimeRangeError`.
|
|
444
|
+
|
|
445
|
+
- Activity reports a change to a `belongs_to` target that the root took
|
|
446
|
+
without a version, such as an author set while `has_paper_trail only:`
|
|
447
|
+
left `author_id` out, when the root's next version moved to another target.
|
|
448
|
+
Only that version's stored state named the target, so the target's own
|
|
449
|
+
versions were not events: its rename went unreported by activity read
|
|
450
|
+
step by step, while the same history read in full showed it in an
|
|
451
|
+
unrelated step.
|
|
452
|
+
|
|
453
|
+
- Activity on a `has_and_belongs_to_many` reports the addition of a record
|
|
454
|
+
that the transaction saving the root created and attached, when the record
|
|
455
|
+
was detached again before the root's next version. Only that transaction's
|
|
456
|
+
root version records the record as a member. Its creation was judged by the
|
|
457
|
+
states before and after the transaction, and the record was a member in
|
|
458
|
+
neither, so the creation was left out: activity reported the record's
|
|
459
|
+
removal but never its addition.
|
|
460
|
+
|
|
461
|
+
- `analyze` with `activity: true` from a version to the same version is
|
|
462
|
+
empty, as is any analysis in which nothing is reported. It reported the
|
|
463
|
+
record as destroyed: its `diff` held a presence change to `nil`, and its
|
|
464
|
+
`to_snapshot` was `nil`.
|
|
465
|
+
|
|
466
|
+
- `analyze_many` and `analyze_scope` without associations raise
|
|
467
|
+
`AmbiguousVersionOrderError` for versions they cannot order, as `timeline`
|
|
468
|
+
and `analyze` already did: versions that share a timestamp and whose ids
|
|
469
|
+
do not count up, such as UUIDs. They read such versions in the order of
|
|
470
|
+
their ids, so a record's steps could follow a random sequence, including
|
|
471
|
+
a destroy and re-creation that never happened.
|
|
472
|
+
|
|
473
|
+
### Development
|
|
474
|
+
|
|
475
|
+
- `ORACLE_SHRINK=1` reduces a failing oracle example to the few steps that
|
|
476
|
+
matter. The generators draw through a random source that keeps each draw
|
|
477
|
+
by step, and the reducer runs the example again with steps left out and
|
|
478
|
+
choices set to the first one, while it still fails the same way. The example
|
|
479
|
+
then reports the reduced history's versions and mismatches, and a file that
|
|
480
|
+
replays it with `ORACLE_REPLAY`. An oracle failure prints the command. The
|
|
481
|
+
replay differential oracle reports each read that differs, with both
|
|
482
|
+
results, rather than only the transactions it made. The consistency checks'
|
|
483
|
+
histories reduce the same way.
|
|
484
|
+
|
|
485
|
+
- `.github/workflows/oracle.yml` runs 200 more oracle seeds each night with
|
|
486
|
+
`ORACLE_STEPS=40`, in eight jobs, from a window that moves 200 seeds a day,
|
|
487
|
+
so each night tries histories no run has. A job reduces its first two
|
|
488
|
+
failing examples and keeps its log and their replay files as an artifact.
|
|
489
|
+
|
|
490
|
+
- `spec/unit/engine_properties_spec.rb` and
|
|
491
|
+
`spec/unit/nested_comparator_properties_spec.rb` check the comparison
|
|
492
|
+
engine over generated snapshots and JSON values, without a database: an
|
|
493
|
+
equal copy compares as no change, a diff applied to the first snapshot gives
|
|
494
|
+
the second, comparing the other way gives the opposite diff, every change
|
|
495
|
+
is real and in order, a carried-forward collection reports what one built
|
|
496
|
+
whole does, and the result is frozen. The oracles compute the diffs they
|
|
497
|
+
expect with the engine, so they cannot catch a bug in it. Of six engine bugs
|
|
498
|
+
injected to try them, the properties caught all six in about a second; the
|
|
499
|
+
engine's own specs missed two, which only integration and association
|
|
500
|
+
examples caught.
|
|
501
|
+
|
|
502
|
+
- `spec/unit/net_changes_properties_spec.rb` checks the fold behind
|
|
503
|
+
`net_changes` over generated histories in which each record has one state:
|
|
504
|
+
the rows of any run of steps fold into each record's change between the
|
|
505
|
+
run's first and last states, the root comes first and then each record by
|
|
506
|
+
its first kept change, the rows that move records in and out leave each, kept
|
|
507
|
+
alone, as its last move left it, and a record that stayed changes only in
|
|
508
|
+
fields a kept row set. Of six fold bugs injected to try them, they caught
|
|
509
|
+
all six, as the fold's own specs do.
|
|
510
|
+
|
|
511
|
+
- `spec/oracle/unversioned_writes_spec.rb` builds seeded histories of saves
|
|
512
|
+
and `update_columns` writes to an article, its comments and its author,
|
|
513
|
+
several to a transaction, and checks every change row against the writes:
|
|
514
|
+
a field's rows chain into the step's change, a row credited to a version
|
|
515
|
+
ends at a value that version recorded, an unversioned row ends at a value
|
|
516
|
+
an `update_columns` wrote, and a write a later version or the current row
|
|
517
|
+
reads has a row of its own. It runs over the whole history, grouped and
|
|
518
|
+
not, and over windows that start and end inside transactions.
|
|
519
|
+
|
|
520
|
+
- Every oracle that reads an activity timeline from end to end also checks
|
|
521
|
+
its net changes (`spec/support/net_changes_check.rb`): with every row
|
|
522
|
+
kept, each record's `before` and `after` must be its state where the step
|
|
523
|
+
of its first row starts and where the timeline ends, and the record must
|
|
524
|
+
be listed exactly when the two differ. The unversioned-writes oracle also
|
|
525
|
+
keeps only the rows of versions and checks that each article and comment
|
|
526
|
+
ends at its last recorded save.
|
|
527
|
+
|
|
528
|
+
- `spec/association/report_sql_work_spec.rb` bounds how a report's SQL grows
|
|
529
|
+
with other records' history in its window, counted in the steps SQLite's
|
|
530
|
+
virtual machine takes, which are the same on every run. A statement that
|
|
531
|
+
reads the window again for each of the roots' versions fails it; one such
|
|
532
|
+
statement, never released, took reports on SQLite from 6 to 44 ms an
|
|
533
|
+
article (see [SQL work](docs/testing.md#sql-work)). The reporting benchmark
|
|
534
|
+
has an `association_window` case: a `report` over articles with their
|
|
535
|
+
comments read through PT-AT, with the README's indexes.
|
|
536
|
+
|
|
537
|
+
- `spec/oracle/shapes_history_spec.rb` compares rebuilt history with plain
|
|
538
|
+
Active Record for shapes the other oracles leave out: polymorphic
|
|
539
|
+
`belongs_to`, `has_many` and `has_one` with `as:`, children that use
|
|
540
|
+
single-table inheritance and change type, an association to one subclass,
|
|
541
|
+
a child's own `belongs_to`, scoped and ranked `has_many` and `has_one`, and
|
|
542
|
+
a default scope. It checks every endpoint, timeline step, activity step,
|
|
543
|
+
window and window split, through `spec/support/graph_oracle.rb`, which
|
|
544
|
+
reads the expected states for any model. It found the first three bugs
|
|
545
|
+
above; a longer run of the replay differential found the fourth.
|
|
546
|
+
`ORACLE_SHOW` prints more than the first five mismatches.
|
|
547
|
+
|
|
548
|
+
- The SQL Server 2022 CI job's database allows snapshot isolation and the
|
|
549
|
+
2019 job's does not, so both ways of reading a call run on CI.
|
|
550
|
+
|
|
551
|
+
- The oracles' transactions take turns between authors, and every window
|
|
552
|
+
split is also read with a `version_scope:` that keeps one author's versions.
|
|
553
|
+
It must report exactly the unfiltered steps of the transactions that author
|
|
554
|
+
saved a version in.
|
|
555
|
+
|
|
556
|
+
- Mutation testing in CI runs in four parallel jobs, each mutating every
|
|
557
|
+
fourth method in scope (`script/mutant_shard.rb`). A pull request that
|
|
558
|
+
changed 84 methods took 33 minutes on one runner, close to the job's
|
|
559
|
+
45-minute limit.
|
|
560
|
+
|
|
561
|
+
- `PAPER_TRAIL_DIFF_SERIALIZER=json` runs the suites with PaperTrail's JSON
|
|
562
|
+
serializer, and a new CI job runs them that way. Before, about 40 of some
|
|
563
|
+
1,800 examples wrote JSON history, and none on the PaperTrail 16 or SQL
|
|
564
|
+
Server jobs. Run with JSON, the suites found no fault in the gem: the specs
|
|
565
|
+
that failed wrote YAML fixtures by hand, were about YAML itself, or read
|
|
566
|
+
times more finely than JSON keeps them (milliseconds), which the gem
|
|
567
|
+
refuses or rounds as documented. Those specs now write fixtures with the
|
|
568
|
+
configured serializer, keep YAML where YAML is the subject, and compare
|
|
569
|
+
times as JSON history holds them.
|
|
570
|
+
|
|
6
571
|
## [0.16.0] - 2026-11-01
|
|
7
572
|
|
|
8
573
|
### Changed
|
|
@@ -62,7 +627,7 @@ project follows [Semantic Versioning](https://semver.org/).
|
|
|
62
627
|
### Fixed
|
|
63
628
|
|
|
64
629
|
- Batch methods with `within:` or `since:` look for transactions that cross
|
|
65
|
-
the window's edges in one statement per
|
|
630
|
+
the window's edges in one statement per 250 records. 0.15.0 wrote a
|
|
66
631
|
separate lookup for each record into the statement, which SQL Server took
|
|
67
632
|
about a second to compile per 200 records, so a report on 10,800 records
|
|
68
633
|
spent nearly two minutes there. On 1.4 million versions, 0.15.0 failed for
|
data/README.md
CHANGED
|
@@ -166,7 +166,8 @@ report.deleted # Reports for those records, or nil when destroy history is m
|
|
|
166
166
|
|
|
167
167
|
`report.analyses` is a hash of reports for records that still exist. Each key is
|
|
168
168
|
`[model_name, id_as_a_string]`. Each value has the net `diff` and an
|
|
169
|
-
`activity_timeline`. `report.roots` returns the selected ActiveRecord objects
|
|
169
|
+
`activity_timeline`. `report.roots` returns the selected ActiveRecord objects,
|
|
170
|
+
and `report.analysis_for(record)` the report for one of them.
|
|
170
171
|
|
|
171
172
|
`include_deleted: true` also builds reports from PaperTrail's destroy versions.
|
|
172
173
|
Read them from `report.deleted` using the same keys:
|
|
@@ -240,9 +241,9 @@ records last. Each value lists that record's rows in time order. Each row
|
|
|
240
241
|
covers one of two things:
|
|
241
242
|
|
|
242
243
|
- **A field**: `attribute` names it, and `change` is `:changed` for an edit.
|
|
243
|
-
For a record that appeared or disappeared, each of its fields
|
|
244
|
-
`:added` or `:removed` row, holding its value in `to` or
|
|
245
|
-
|
|
244
|
+
For a record that appeared or disappeared, each of its fields that is not
|
|
245
|
+
`nil` gets an `:added` or `:removed` row, holding its value in `to` or
|
|
246
|
+
`from`. An empty string or `false` still gets one.
|
|
246
247
|
- **A whole record**: `attribute` is `nil`, and `change` is `:added` or
|
|
247
248
|
`:removed`. The record was created or deleted, a comment joined or left the
|
|
248
249
|
article, or a `belongs_to` pointed somewhere new, which gives a `:removed`
|
|
@@ -251,11 +252,45 @@ covers one of two things:
|
|
|
251
252
|
|
|
252
253
|
`record` is the record the row is about, or `nil` for the article itself, and
|
|
253
254
|
`association_path` is how it was reached, such as `["comments"]`. `to_h` adds
|
|
254
|
-
the
|
|
255
|
-
and `transaction_id`.
|
|
256
|
-
|
|
255
|
+
the version that made the change: `version_id`, `event`, `whodunnit`,
|
|
256
|
+
`recorded_at`, and `transaction_id`. That is the version of the row's own
|
|
257
|
+
record, even when another record's event opens the step, as in a transaction.
|
|
258
|
+
A record that joined or left through another record's change, such as an
|
|
259
|
+
article's new author, names the step's first event. `row.source` is the
|
|
257
260
|
`ActivityBoundary` itself.
|
|
258
261
|
|
|
262
|
+
A write made without a version, such as `update_columns`, shows up in the
|
|
263
|
+
step of the record's previous change. Pass `recorded_changes: true` to
|
|
264
|
+
`report` to tell it apart: the part of a change PaperTrail did not record
|
|
265
|
+
gets a row of its own, with `row.unversioned?` true and no `version_id`,
|
|
266
|
+
`event`, `whodunnit`, or `recorded_at`. To list only what versions recorded:
|
|
267
|
+
|
|
268
|
+
```ruby
|
|
269
|
+
recorded = report.change_rows.transform_values { |rows| rows.reject(&:unversioned?) }
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
Some writes cannot be told apart, such as one to a column `has_paper_trail`
|
|
273
|
+
ignores; see [change rows](docs/reference.md#change-rows).
|
|
274
|
+
|
|
275
|
+
For one entry per record instead, `net_changes` folds the rows a block keeps
|
|
276
|
+
into each record's fields before and after them. This one keeps the changes
|
|
277
|
+
people made, leaving out writes saved without a version, which have no
|
|
278
|
+
author:
|
|
279
|
+
|
|
280
|
+
<!-- executable:recipe-net-changes -->
|
|
281
|
+
```ruby
|
|
282
|
+
report = PaperTrailDiff.report(
|
|
283
|
+
Article.all, since: 1.day.ago, limit: 100, associations: [:comments],
|
|
284
|
+
snapshots: true, recorded_changes: true
|
|
285
|
+
)
|
|
286
|
+
|
|
287
|
+
changes = report.net_changes { |row| row.source.whodunnit }
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
Each value lists the article, then each comment that changed, was added, or
|
|
291
|
+
was removed, with its `before` and `after` fields and the `diff` between
|
|
292
|
+
them. See [net changes](docs/reference.md#net-changes).
|
|
293
|
+
|
|
259
294
|
`change_rows` is also on an `Analysis` built with `activity: true` and on each
|
|
260
295
|
activity step. Labels, grouping, and formatting are left to your application.
|
|
261
296
|
|