paper_trail-actor 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b84892ec641d12e2f30f9779c934369db0ff3b3246cc6c12837f3750a704392
-  data.tar.gz: 6d2dcde8f48e153acf1680c0f9dc278c2a5ed696dda0341557d0f104f12e5dbb
+  metadata.gz: 8d8d84d52637e0114f5ab6c64b3caf0d10b2a94d6049d1e4c1ec0826d4dd94f4
+  data.tar.gz: fdabf9efe06ee201f706b17fc47fc75ffe590c57657c479b6b4bb1a26428eb94
 SHA512:
-  metadata.gz: 0cdefc8cb362df6ae343b23d60ff02ba28a3ebded2cc51f4a7e292cf70587b6a826074e0ed2a3554c5ff73f79893966b84314209247b509f9681153f818b45ff
-  data.tar.gz: 8a50a20d5d6183cd6d0871ac24f3c84a6461339ec08fd1aacbd78e95ae0a6a207601720161d268288e170605df012aae47f4cb05533525ae0e39f462583e4793
+  metadata.gz: 50b13f56e781102f2c2da25054ea6530feff8d544a8320bc912157f4cb639f9a559ee6edc2166f58295aac8e7f7c716f06ea8f1abddc1fcf873a92f1e17ab3fd
+  data.tar.gz: ceec6f0626b24475afb00c413607491cb9456bab684a4ad835dc77798fbb3cf910a007c97e51ce5eb884dc176a2d03eb8828849704e5f5b3e342d5a6c054b8c2

data/CHANGELOG.md

@@ -70,3 +70,17 @@
 
 - [#10](https://github.com/tttffff/paper_trail-actor/pull/10) Allow other object types.
   Can now use any object that implements globalid, not just ActiveRecord objects.
+ 
+## [0.5.1] - 2025-11-15
+
+### Breaking Changes
+
+- None
+
+### Added
+
+- None
+
+### Fixed
+
+- Explicitly set required ruby version.

data/README.md

@@ -1,26 +1,41 @@
 # PaperTrail-Actor
 
-This gem is an extension for [PaperTrail](https://github.com/paper-trail-gem/paper_trail) that allows you to set an `ActiveRecord` object as the "whodunnit" field. This enhancement provides more granular tracking of who made changes, making it easier to trace modifications in your application.
+Track changes in your Rails application with precision. PaperTrail-Actor extends [PaperTrail](https://github.com/paper-trail-gem/paper_trail) to store full ActiveRecord objects (not just IDs) as the actor responsible for changes.
 
-## Features
+**Problem it solves:** When both `Admin` and `User` models can modify records, storing only an ID makes it impossible to know which model type made the change. PaperTrail-Actor stores GlobalIDs to uniquely identify actors across different model types.
+
+## Table of Contents
 
-- **Set an ActiveRecord Object for Whodunnit:** Use an `ActiveRecord` object to track who made changes.
-- **Return the ActiveRecord Object:** The method `#actor` can be used to get the object responsible for changes.
-- **Coexistence with Existing Versions:** Works seamlessly alongside existing PaperTrail versions, regardless of when they were created.
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Setup](#basic-setup)
+  - [Supported Object Types](#supported-object-types)
+  - [Controller Integration](#controller-integration)
+  - [Migrating Existing Data](#migrating-existing-data)
+- [How It Works](#how-it-works)
+
+## Features
 
-## How it works
+- **Store any ActiveRecord object** as the actor who made changes
+- **Retrieve the full object** with a simple `#actor` method
+- **Backward compatible** with existing PaperTrail versions
+- **Flexible** - works with strings, unpersisted records, and non-ActiveRecord objects
 
-This gem works by storing the [globalid](https://github.com/rails/globalid) to the whodunnit field of PaperTrail version tables. This allows you to add different object types to the whodunnit field, know exactly which object is responsible, and retrive that object with ease.
+## Requirements
 
-For example, if you have both `Admin` objects and `User` objects that are capable of making changes, this gem ensures that you can clearly identify who made the change instead of using purely an ID and not knowing if it was for an `Admin` or a `User`
+- Ruby 2.7+
+- Rails 6.0+
+- PaperTrail 11.0+
 
 ## Installation
 
-1. Add `paper_trail-actor` to your Gemfile:
+1. Add to your Gemfile:
   ```ruby
   gem "paper_trail-actor"
   ```
-2. Run the following command:
+2. Install the gem:
   ```sh
   bundle install
   ```
@@ -29,95 +44,139 @@ For example, if you have both `Admin` objects and `User` objects that are capabl
 
 ### Basic Setup
 
-To use this gem, you first need to set a user (or any `ActiveRecord` object) to the `whodunnit` field.
+Set any ActiveRecord object as the actor responsible for changes:
 
 ```ruby
-product = Product.find(42)
 admin = Admin.find(1)
-
 PaperTrail.request.whodunnit = admin
-PaperTrail.request.whodunnit # "gid://app/Admin/1"
-PaperTrail.request.actor # Returns the `Admin` object with id 1
-```
 
-When you update the product, PaperTrail will remember who made the change:
-
-```ruby
-product.update(name: "Ice cream")
-product.versions.last.whodunnit # "gid://app/Admin/1"
-product.versions.last.actor # Returns the `Admin` object with id 1
+# Now all changes will be attributed to this admin
+# See Supported Object Types section below for detailed examples
 ```
 
-### Flexible Whodunnit
+### Supported Object Types
 
-The gem is designed to be flexible. You can set `whodunnit` with various types of objects:
+The gem handles various object types gracefully:
 
-- **Strings:**
-  ```ruby
-  PaperTrail.request.whodunnit = "Alex the admin" # "Alex the admin"
-  ```
+**Persisted ActiveRecord objects:**
+```ruby
+admin = Admin.find(1)
+product = Product.find(42)
 
-- **New/unpersisted ActiveRecord Objects:**
-  ```ruby
-  PaperTrail.request.whodunnit = Admin.new # Sets the string representation of the admin
-  ```
+PaperTrail.request.whodunnit = admin
+PaperTrail.request.whodunnit # => "gid://app/Admin/1"
+PaperTrail.request.actor     # => #<Admin id: 1>
 
-- **Non-ActiveRecord Objects:**
-  ```ruby
-  class Job
-    def to_s
-      "A job in the system"
-    end
-  end
+# Make changes - PaperTrail will track the actor
+product.update(name: "Ice cream")
+product.versions.last.whodunnit # => "gid://app/Admin/1"
+product.versions.last.actor     # => #<Admin id: 1>
+```
 
-  PaperTrail.request.whodunnit = Job.new  # "A job in the system"
-  ```
+**Strings:**
+```ruby
+PaperTrail.request.whodunnit = "Alex the admin"
+PaperTrail.request.whodunnit # => "Alex the admin"
+PaperTrail.request.actor     # => "Alex the admin"
+```
 
-When you update the product, PaperTrail will store the string for who made the change:
+**New/unpersisted ActiveRecord objects:**
+```ruby
+PaperTrail.request.whodunnit = Admin.new(name: "New Admin")
+# Cannot get a globalid for an unpersisted object. So we use the `#to_s` for the object.
+PaperTrail.request.whodunnit # => "#<Admin:0x00007f8e8c0a0b80>"
+PaperTrail.request.actor     # => "#<Admin:0x00007f8e8c0a0b80>"
+```
 
+**Non-ActiveRecord objects:**
 ```ruby
-product.update(name: "Ice cream")
-product.versions.last.whodunnit # "A job in the system"
-product.versions.last.actor # "A job in the system"
+class BackgroundJob
+  def to_s
+    "BackgroundJob-#{object_id}"
+  end
+end
+
+PaperTrail.request.whodunnit = BackgroundJob.new
+PaperTrail.request.whodunnit # => "BackgroundJob-12345"
+PaperTrail.request.actor     # => "BackgroundJob-12345"
 ```
 
-### Updating Existing Versions
+### Controller Integration
 
-If you have existing PaperTrail versions and need to update them, you can do so by:
+Set the actor automatically in your controllers using PaperTrail's built-in callback:
 
 ```ruby
-first_product_version = product.versions.first
-admin_id = first_product_version.actor # For example, "1"
-admin = Admin.find_by(id: admin_id)
-
-if admin.present?
-  first_product_version.whodunnit = admin
-  first_product_version.save
+class ApplicationController < ActionController::Base
+  before_action :set_paper_trail_whodunnit
 end
 ```
 
-### Setting whodunnit with a controller callback
+If your controller has a `#current_user` method, PaperTrail-Actor will automatically use it and attribute all changes within the request cycle to that user.
 
-You can set the user for PaperTrail in the same way that the [PaperTrail documentation states](https://github.com/paper-trail-gem/paper_trail#setting-whodunnit-with-a-controller-callback).
+```ruby
+# In your CRUD actions
+def update
+  # Nothing else required here to attribute the user as the actor.
+  @product.update(product_params)
+  @product.versions.last.actor # => #<User id: 42> (full User object)
+end
+```
 
-However, setting this to an ActiveRecord object now records the globalid. It also allows the object to be retrived from created PaperTrail versions with the `#actor` method.
+**Before PaperTrail-Actor:**
+```ruby
+# whodunnit was just a string like "42"
+version.whodunnit # => "42"
+# You couldn't tell if this was User 42 or Admin 42
+```
 
-If your controller has a `#current_user` method, PaperTrail-Actor will assign the globalid of the current user to whodunnit. If your controller doesn't have a `#current_user`, or if the current user is `nil`, then whodunnit will not be set.
+**After PaperTrail-Actor:**
+```ruby
+# whodunnit stores the full GlobalID
+version.whodunnit # => "gid://app/User/42"
+version.actor     # => #<User id: 42>
+# Now you know exactly who to attribute the change to
+```
 
-You may want set `#user_for_paper_trail` to call a different method to find out who is responsible. To do so, override the `#user_for_paper_trail` method in your controller:
+Override `#user_for_paper_trail` to customize the actor selection logic:
 
 ```ruby
 class ApplicationController < ActionController::Base
   before_action :set_paper_trail_whodunnit
 
+  private
+
   def user_for_paper_trail
     logged_in? ? current_admin : "Public user"
   end
 end
 ```
 
-## Contributing
+### Migrating Existing Data
+
+**When to migrate:** Install PaperTrail-Actor on an existing app with PaperTrail data.
+
+**How to migrate:** Convert existing string IDs to GlobalIDs:
+
+```ruby
+# Find a version with a plain ID
+version = product.versions.first
+# => #<PaperTrail::Version id: 1, whodunnit: "123">
+
+# Convert to GlobalID
+admin = Admin.find_by(id: version.whodunnit)
+if admin.present?
+  version.update!(whodunnit: admin)
+  version.whodunnit # => "gid://app/Admin/123"
+  version.actor     # => #<Admin id: 123>
+end
+```
+
+## How It Works
+
+PaperTrail-Actor serializes ActiveRecord objects using [GlobalID](https://github.com/rails/globalid) and stores them in PaperTrail's `whodunnit` column. This enables:
+
+- **Type-safe actor identification**: `gid://app/Admin/1` vs `gid://app/User/1`
+- **Automatic deserialization**: Call `#actor` to get back the original ActiveRecord object
+- **Graceful fallback**: Non-ActiveRecord objects are stored as strings
 
-1. Please add tests for PRs that are created.
-2. Run the tests `bundle exec rake spec` to ensure that they all pass.
-3. Lint the code `bundle exec rake standard:fix` to ensure that convention is maintained.
+For example, if you have both `Admin` and `User` models that can make changes, this gem ensures you can clearly identify who made the change instead of using only an ID without knowing the model type.

data/lib/paper_trail-actor/version.rb

@@ -1,3 +1,3 @@
 module PaperTrailActor
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail-actor
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - tttffff
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-29 00:00:00.000000000 Z
+date: 2025-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: paper_trail
@@ -108,8 +108,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: An extension to PaperTrail. Using this gem, you can fetch the ActiveRecord
-  object that was responsible for changes
+description: An extension to PaperTrail that allows you to retrieve the ActiveRecord
+  object (actor) that was responsible for creating or modifying records, enabling
+  better audit trails and change attribution.
 email:
 - tristanfellows@icloud.com
 executables: []
@@ -141,7 +142,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -151,6 +152,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: An extension to PaperTrail. Using this gem, you can fetch the ActiveRecord
-  object that was responsible for changes
+summary: Fetch the ActiveRecord object responsible for PaperTrail changes
 test_files: []