PaperTrailHistory

A Rails engine providing a comprehensive web interface for managing PaperTrail versions. View, search, filter, and restore audit trail records with an intuitive Bootstrap-styled interface.

• List All Trackable Models: Discover all models in your application that use has_paper_trail
• Browse Version History: View all versions for specific models or individual records
• Advanced Filtering: Filter versions by event type, user, date range, and search content
• Detailed Version View: See exactly what changed in each version with before/after comparisons
• Restore Functionality: Safely restore records to previous versions with confirmation
• Responsive Design: Clean, Bootstrap-styled interface that works on all devices
• Breadcrumb Navigation: Easy navigation between models, records, and versions

Add this line to your application's Gemfile:

gem "paper_trail_history"

And then execute:

$ bundle install

Mount the engine in your routes file (config/routes.rb):

Rails.application.routes.draw do
  mount PaperTrailHistory::Engine, at: '/revisions'
  # your other routes...
end

This engine requires:

• Rails >= 7.2
• PaperTrail >= 15.0 (configured with has_paper_trail in your models)

Make sure you have PaperTrail properly configured in your Rails application before using this engine.

After mounting the engine, navigate to /revisions (or whatever path you chose) in your browser to access the interface.

1. Models Overview (/revisions/models)

   • Lists all models with paper trail enabled
   • Shows version counts for each model
   • Quick access to recent versions

2. Model Versions (/revisions/models/:model_name/versions)

   • View all versions for a specific model
   • Filter by event type, user, date range
   • Search within version content
   • Pagination support

3. Record Versions (/revisions/models/:model_name/:record_id/versions)

   • View version history for a specific record
   • See current record state vs historical versions

4. Version Details (/revisions/versions/:id)

   • Detailed view of what changed in a specific version
   • Side-by-side comparison of old vs new values
   • Restore functionality with confirmation

The interface provides several ways to filter and search versions:

• Event Type: Filter by create, update, or destroy events
• User: Filter by who made the changes (whodunnit)
• Date Range: Show versions within specific date ranges
• Content Search: Search within the stored object changes

You can restore any version (except create events) by:

1. Navigate to the version details page
2. Click "Restore This Version"
3. Confirm the restoration

Note: Restoring a version will create a new version entry, so you can always see the restoration in the audit trail.

After cloning the repository, run the setup script to get started:

# Automated setup - installs dependencies, sets up database, runs tests
bin/setup

This script will:

• Install bundler and project dependencies
• Set up the test dummy app with database and seed data
• Run initial tests to verify everything works
• Run the linter to check code quality

If you prefer manual setup:

# Install dependencies
bundle install

# Set up test database with sample data
cd test/dummy
bundle install --gemfile=../../Gemfile
bundle exec rails db:prepare
bundle exec rails db:seed
cd ../..

# Run all tests
bundle exec rake test

# Run integration tests only
bundle exec rake test:integration

# Run specific test file
bundle exec ruby -I test test/models/paper_trail_history/trackable_model_test.rb

# Run with verbose output
bundle exec rake test TESTOPTS="-v"

# Run code quality checks
bundle exec rubocop

# Test models only
bundle exec rake test TEST="test/models/**/*_test.rb"

# Test controllers only  
bundle exec rake test TEST="test/controllers/**/*_test.rb"

# Test integration features
bundle exec rake test TEST="test/integration/**/*_test.rb"

The test/dummy directory contains a full Rails application with sample models and data for testing:

# Start the development server (from project root)
bin/dummy

# Alternative: manual approach
cd test/dummy && bundle exec rails server

# Visit the engine interface
open http://localhost:3000/paper_trail_history

The dummy app includes:

• User, Post, Comment models - Standard PaperTrail setup
• Product model - Custom version table (ProductVersion)
• Rich seed data - Various change types, workflows, and scenarios
• I18n translations - Proper model pluralization

For comprehensive compatibility testing, use the provided Gemfiles:

# Test against Rails 7.2
BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle install
BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle exec rake test

# Test against Rails 8.0
BUNDLE_GEMFILE=gemfiles/rails_8.0.gemfile bundle install  
BUNDLE_GEMFILE=gemfiles/rails_8.0.gemfile bundle exec rake test

# Test against Rails main branch
BUNDLE_GEMFILE=gemfiles/rails_main.gemfile bundle install
BUNDLE_GEMFILE=gemfiles/rails_main.gemfile bundle exec rake test

The project uses GitHub Actions to test against multiple Ruby and Rails versions. See .github/workflows/ci.yml for the full matrix configuration.

1. Fork the project
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

The gem is available as open source under the terms of the MIT License.

Kindly supported by aifinyo AG