Migrate to ActiveAdmin 4, Rails 8, and rails-settings-cached 2.x

.github/workflows/ci.yml

@@ -0,0 +1,114 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.3', '3.4']
+        gemfile:
+          - rails_7.2_active_admin_4.x
+          - rails_8.0_active_admin_4.x
+
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/${{ matrix.gemfile }}.gemfile
+      RAILS_ENV: test
+      PLAYWRIGHT_BROWSERS_PATH: ${{ github.workspace }}/ms-playwright
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      # Cache APT packages for Playwright dependencies
+      - name: Cache APT packages
+        uses: awalsh128/cache-apt-pkgs-action@v1.5.3
+        with:
+          packages: libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libdbus-1-3 libatspi2.0-0 libx11-6 libxcomposite1 libxdamage1 libxext6 libxfixes3 libxrandr2 libgbm1 libxcb1 libxkbcommon0 libpango-1.0-0 libcairo2 libasound2
+          version: 1.0
+          execute_install_scripts: true
+
+      # Get Playwright version for cache key
+      - name: Get Playwright version
+        id: playwright-version
+        run: |
+          PLAYWRIGHT_VERSION=$(cd spec/internal && npm ls @playwright/test 2>/dev/null | grep @playwright/test | sed 's/.*@//' | head -1)
+          if [ -z "$PLAYWRIGHT_VERSION" ]; then
+            PLAYWRIGHT_VERSION=$(npx playwright --version | sed 's/Version //')
+          fi
+          echo "version=$PLAYWRIGHT_VERSION" >> $GITHUB_OUTPUT
+
+      # Cache Playwright browsers
+      - name: Cache Playwright browsers
+        id: playwright-cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ github.workspace }}/ms-playwright
+          key: ${{ runner.os }}-playwright-${{ steps.playwright-version.outputs.version }}-${{ hashFiles('spec/internal/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-playwright-${{ steps.playwright-version.outputs.version }}-
+            ${{ runner.os }}-playwright-
+
+      - name: Install npm dependencies
+        run: |
+          cd spec/internal
+          npm install
+
+      - name: Build JavaScript assets
+        run: |
+          cd spec/internal
+          npm run build:js
+
+      - name: Build CSS assets
+        run: |
+          cd spec/internal
+          npm run build:css
+
+      - name: Install Playwright browsers
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+        run: npx playwright install chromium
+
+      - name: Setup test database
+        run: |
+          cd spec/internal
+          ./bin/rails db:create db:schema:load RAILS_ENV=test
+
+      - name: Run tests with coverage
+        run: bundle exec rspec --format progress
+
+      - name: Upload coverage
+        if: matrix.ruby == '3.4' && matrix.gemfile == 'rails_8.0_active_admin_4.x'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage/
+          retention-days: 7
+
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: Run RuboCop
+        run: bundle exec rubocop --force-exclusion

.gitignore

@@ -16,3 +16,9 @@
 .idea
 mkmf.log
 /gemfiles/*.lock
+spec/internal/node_modules/
+spec/internal/app/assets/builds/
+spec/internal/log/*.log
+spec/internal/storage/*.sqlite3*
+spec/internal/tmp/
+spec/internal/package-lock.json

.rubocop.yml

@@ -0,0 +1,89 @@
+# RuboCop configuration for activeadmin_settings_cached
+
+plugins:
+  - rubocop-capybara
+  - rubocop-rake
+  - rubocop-rspec
+  - rubocop-rspec_rails
+
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 3.2
+  Exclude:
+    - 'spec/internal/**/*'
+    - 'gemfiles/**/*'
+    - 'vendor/**/*'
+    - 'node_modules/**/*'
+    - 'tmp/**/*'
+
+# Gem
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+# RSpec
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/ExampleLength:
+  Max: 10
+
+RSpec/ContextWording:
+  Enabled: false
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/ExpectInHook:
+  Enabled: false
+
+RSpec/NoExpectationExample:
+  Enabled: false
+
+RSpec/BeforeAfterAll:
+  Enabled: false
+
+# Style preferences
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+# Layout
+Layout/LineLength:
+  Max: 130
+  Exclude:
+    - 'activeadmin_settings_cached.gemspec'
+
+# Metrics
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'config/**/*'
+    - 'lib/tasks/**/*'
+    - 'activeadmin_settings_cached.gemspec'
+
+Metrics/MethodLength:
+  Max: 25
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 30
+  Exclude:
+    - 'spec/**/*'
+
+# Lint
+Lint/DuplicateMethods:
+  Enabled: false

Appraisals

@@ -1,7 +1,28 @@
 # frozen_string_literal: true
 
-appraise 'rails5.1' do
-  gem 'rails', '~> 5.1.0'
-  gem 'inherited_resources'
-  gem 'listen'
+appraise 'rails-7.0-active-admin-4.x' do
+  gem 'rails', '~> 7.0.0'
+  gem 'activeadmin', '~> 4.0.0.beta16'
+  gem 'propshaft'
+  gem 'importmap-rails'
+end
+
+appraise 'rails-7.1-active-admin-4.x' do
+  gem 'rails', '~> 7.1.0'
+  gem 'activeadmin', '~> 4.0.0.beta16'
+  gem 'propshaft'
+  gem 'importmap-rails'
+end
+
+appraise 'rails-7.2-active-admin-4.x' do
+  gem 'rails', '~> 7.2.0'
+  gem 'activeadmin', '~> 4.0.0.beta16'
+  gem 'propshaft'
+  gem 'importmap-rails'
+end
+
+appraise 'rails-8.0-active-admin-4.x' do
+  gem 'rails', '~> 8.0.0'
+  gem 'activeadmin', '~> 4.0.0.beta16'
+  # Propshaft and importmap are default in Rails 8
 end

CHANGELOG.md

@@ -1,3 +1,150 @@
+# v3.0.0 (2025-10-10)
+
+**Upgrade Guide:** See [docs/upgrade-to-v3.md](docs/upgrade-to-v3.md) for detailed upgrade instructions.
+
+## Breaking Changes
+
+### Minimum Version Requirements
+- **Ruby**: 3.2+ (dropped support for Ruby < 3.2)
+- **Rails**: 7.0+ (dropped support for Rails < 7.0)
+- **ActiveAdmin**: 2.0+ with full ActiveAdmin 4.x support
+- **Asset Pipeline**: Propshaft (Rails 8 default) and Sprockets support
+
+### Rails 7+ Compatibility
+- Updated `redirect_to(:back)` to `redirect_back_or_to` for Rails 7+ compatibility
+- Updated engine initialization to use modern Rails loading patterns
+- Added `ActiveSupport.on_load(:active_admin)` for proper initialization timing
+
+### Testing Infrastructure
+- **Removed**: Poltergeist (PhantomJS)
+- **Added**: Capybara Playwright Driver for modern browser testing
+- **Migrated**: From dynamic Rails app generation to Combustion-based test setup
+- **Added**: GitHub Actions CI with matrix testing (Ruby 3.2-3.4, Rails 7.0-8.0)
+- Test app now runnable via `bundle exec rackup` for development
+
+## Added
+
+### ActiveAdmin 4 Support
+- Full compatibility with ActiveAdmin 4.0.0.beta16+
+- Support for Tailwind CSS-based ActiveAdmin themes
+- Propshaft asset pipeline integration
+- Modern esbuild + Tailwind CSS build pipeline in test app
+
+### Development Dependencies
+- `combustion` (~> 1.4) - Modern Rails engine testing
+- `capybara-playwright-driver` - Reliable browser automation
+- `database_cleaner-active_record` - Database state management
+- `puma` - Modern web server
+- `rspec-rails` (~> 6.0) - Latest RSpec Rails integration
+
+### Test Infrastructure
+- Complete Combustion-based test app in `spec/internal/`
+- Package.json with esbuild and Tailwind CSS configuration
+- Automated asset building via rake tasks
+- GitHub Actions CI with comprehensive matrix testing
+- Support for testing multiple Rails versions via Appraisals
+
+### Documentation
+- Comprehensive ActiveAdmin 4 migration plan
+- Updated README with ActiveAdmin 4 setup instructions
+- CI/CD setup documentation
+
+## Changed
+
+### Engine Configuration
+- Updated to use proper `ActiveSupport.on_load(:active_admin)` hooks
+- Improved initialization order for better compatibility
+- Modern Rails engine configuration patterns
+
+### Test Suite
+- Migrated from custom Rails template to Combustion
+- Updated all specs for modern Capybara matchers
+- Improved test reliability with Playwright
+- Added proper asset building in CI pipeline
+
+### Dependencies
+- Updated `activeadmin` dependency to `['>= 2.0', '< 5']`
+- Updated development dependencies to modern versions
+- Removed legacy testing dependencies (Poltergeist, Coveralls)
+- Added Appraisals for multi-version testing
+
+## Removed
+
+- Dropped Ruby 2.x and 3.0-3.1 support
+- Dropped Rails 5.x and 6.x support
+- Removed Poltergeist browser testing
+- Removed Travis CI configuration
+- Removed dynamic Rails app generation in tests
+- Removed legacy therubyracer dependency
+
+## Migration Guide
+
+### Upgrading from v2.x
+
+1. **Update Ruby and Rails versions**
+   ```ruby
+   # Minimum versions required
+   ruby '>= 3.2'
+   gem 'rails', '>= 7.0'
+   gem 'activeadmin', '>= 2.0'
+   ```
+
+2. **For ActiveAdmin 4 users**
+   - Ensure Tailwind CSS is configured in your application
+   - Include gem paths in your `tailwind.config.js`:
+     ```javascript
+     content: [
+       './vendor/bundle/ruby/*/gems/activeadmin_settings_cached-*/app/**/*.rb',
+     ]
+     ```
+
+3. **Test your settings page**
+   - The DSL API remains unchanged
+   - Settings display and functionality work the same way
+   - Check redirect behavior in your `after_save` callbacks
+
+### ActiveAdmin 2.x vs 4.x
+
+This gem supports both ActiveAdmin 2.x and 4.x:
+- **ActiveAdmin 2.x**: Works with existing setup, no changes required
+- **ActiveAdmin 4.x**: Requires Tailwind CSS configuration (see README)
+
+## Development
+
+### Running the Test App
+
+```bash
+# Install dependencies
+bundle install
+cd spec/internal
+npm install
+
+# Build assets
+npm run build
+
+# Start server
+cd ../..
+bundle exec rackup
+
+# Visit http://localhost:9292/admin
+```
+
+### Running Tests
+
+```bash
+# All tests
+bundle exec rspec
+
+# Specific Rails version
+bundle exec appraisal rails-8.0-activeadmin-4.x rspec
+```
+
+## Credits
+
+Special thanks to the ActiveAdmin community and gem maintainers whose documentation and examples guided this modernization effort.
+
+---
+
 # v2.3.1 2018-05-22
 
 ## Changed