activeadmin-tom_select 4.1.0

data/docs/propshaft-upgrade.md

@@ -0,0 +1,484 @@
+# Upgrading from Sprockets to Propshaft
+
+Propshaft has a smaller scope than Sprockets, therefore migrating to it will also require you to adopt the [jsbundling-rails](https://github.com/rails/jsbundling-rails) and [cssbundling-rails](https://github.com/rails/cssbundling-rails) gems. This guide will assume your project follows Rails 6.1 conventions of using [webpacker](https://github.com/rails/webpacker) to bundle javascript, [sass-rails](https://github.com/rails/sass-rails) to bundle css and [sprockets](https://github.com/rails/sprockets) to digest assets. Finally, you will also need [npx](https://docs.npmjs.com/cli/v7/commands/npx) version 7.1.0 or later installed.
+
+Propshaft depends on Rails 7, so you will need to upgrade to Rails 7+ before starting the migration.
+
+## 1. Migrate from Webpacker to jsbundling-rails
+
+Start by following these steps:
+
+1. Replace `webpacker` with `jsbundling-rails` in your Gemfile;
+2. Run `./bin/bundle install`;
+3. Run `./bin/rails javascript:install:webpack`;
+4. Remove the file `config/initializers/assets.rb`;
+5. Remove the file `bin/webpack`;
+6. Remove the file `bin/webpack-dev-server`;
+7. Remove the folder `config/webpack` (note: any custom configuration should be migrated to the new `webpack.config.js` file);
+8. Remove the file `config/webpacker.yml`;
+9. Replace all instances of `javascript_pack_tag` with `javascript_include_tag` and add `defer: true` to them.
+
+After you are done you will notice that the install step added various files to your project and updated some of the existing ones.
+
+**The new 'bin/dev' and 'Procfile.dev' files**
+
+The `./bin/dev` file is a shell script that uses [foreman](https://github.com/ddollar/foreman) and `Procfile.dev` to start two processes in a single terminal: `rails s` and `yarn build`. The latter replaces `webpack-dev-server` for bundling and watching for changes in javascript files.
+
+**The 'build' attribute added to package.json**
+
+This is the command that `yarn build` will use to bundle javascript files.
+
+**The new 'webpack.config.js' file**
+
+In `webpacker` this file was hidden inside the gem, but now you can edit it directly. If you had custom configuration in `config/webpack` you can move them to here. Projects with multiple entrypoints will need to adjust the `entry` attribute:
+
+```js
+module.exports = {
+  entry: {
+    application: "./app/javascript/application.js",
+    admin: "./app/javascript/admin.js"
+  }
+}
+```
+
+**The 'link_tree' directive added to 'app/assets/manifest.js'**
+
+This tells Sprockets to include the files in `app/assets/builds` during `assets:precompile`. This is the folder where `yarn build` will place the bundled files, so make sure you commit it to the repository and don't delete it when cleaning assets. 
+
+**What about babel?**
+
+If you would like to continue using babel for transpiling, you will need to configure it manually. First, open `webpack.config.js` and add this:
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.(js)$/,
+        exclude: /node_modules/,
+        use: ['babel-loader']
+      }
+    ]
+  }
+}
+```
+
+Then open `package.json` and add this:
+```json
+"babel": {
+  "presets": [
+    "./webpack.babel.js"
+  ]
+}
+```
+
+Finally, download [webpackers babel preset](https://github.com/rails/webpacker/blob/master/package/babel/preset.js) file and place it in the same directory as `package.json` with the name `webpack.babel.js`.
+
+**Module resolution**
+
+Webpacker included the `source_path` (default: `app/javascript/`) into module resolution, so a statement like `import 'channels'` imported `app/javascript/channels/`. After migrating to `jsbundling-rails` this is no longer the case. You will need to update your `webpack.config.js` to include the following if you wish to maintain that behavior:
+
+```javascript
+module.exports = {
+  // ...
+  resolve: {
+    modules: ["app/javascript", "node_modules"],
+  },
+  //...
+}
+```
+
+Alternatively, you can change modules to use relative imports, for example:
+```diff
+- import 'channels'
++ import './channels'
+```
+
+### Extracting Sass/SCSS from JavaScript
+
+In webpacker it is possible to extract Sass/SCSS from JavaScript by enabling `extract_css` in `webpacker.yml`. This allows for including those source files in JavaScript, e.g. `import '../scss/application.scss`
+
+If you wish to keep this functionality follow these steps:
+
+1. Run `yarn add mini-css-extract-plugin sass sass-loader css-loader`;
+2. Update your `webpack.config.js` to require `mini-css-extract-plugin` and configure the loaders (see example below).
+
+Example `webpack.config.js`:
+
+```javascript
+const path    = require("path")
+const webpack = require("webpack")
+const MiniCssExtractPlugin = require("mini-css-extract-plugin")
+
+module.exports = {
+  mode: "production",
+  devtool: "source-map",
+  entry: {
+    application: "./app/javascript/application.js"
+  },
+  resolve: {
+    modules: ["app/javascript", "node_modules"],
+  },
+  output: {
+    filename: "[name].js",
+    sourceMapFilename: "[file].map",
+    path: path.resolve(__dirname, "app/assets/builds"),
+  },
+  plugins: [
+    new MiniCssExtractPlugin(),
+    new webpack.optimize.LimitChunkCountPlugin({
+      maxChunks: 1
+    })
+  ],
+  module: {
+    rules: [
+      {
+        test: /\.s[ac]ss$/i,
+        use: [MiniCssExtractPlugin.loader, "css-loader", "sass-loader"],
+      },
+    ],
+  },
+}
+```
+
+## 2. Migrate from sass-rails to cssbundling-rails
+
+Note: if your application used Webpacker's `extract_css` to build your CSS and did not require `sass-rails`, you can skip this section.
+
+Start by following these steps:
+
+1. Add `cssbundling-rails` to your Gemfile;
+2. Run `./bin/bundle install`;
+3. Run `./bin/rails css:install:sass`.
+
+After you are done you will notice that the install step updated some files.
+
+**The new process in 'Procfile.dev'**
+
+Just like the javascript process, this one will bundle and watch for changes in css files.
+
+**The 'build:css' attribute added to package.json**
+
+This is the command `yarn build` will use to bundle css files.
+
+**The 'link_tree' directive removed from 'app/assets/manifest.js'**
+
+Now that the CSS files will be placed into `app/assets/build`, Sprockets no longer needs to worry about the `app/assets/stylesheets` folder. If you have any other `link_tree` for css files, remove them too.
+
+### Configuring multiple entrypoints
+
+Sprockets will only compile files in the root directories listed in `manifest.js`, but the sass package that `yarn build` uses will also check subfolders, which might cause compilation errors if your scss files are using features like `@import` and variables. This means that if you have multiple entry points in your app, you have some extra work ahead of you. 
+
+Let's assume you have the following structure in your `app/asset/stylesheets` folder:
+
+```
+stylesheets/admin.scss
+stylesheets/admin/source_1.scss
+stylesheets/admin/source_2.scss
+stylesheets/application.scss
+stylesheets/application/source_1.scss
+stylesheets/application/source_2.scss
+```
+
+Start by your separating your entrypoints from your other files, and adjusting all `@import` for the new structure:
+
+```
+stylesheets/entrypoints/admin.scss
+stylesheets/entrypoints/application.scss
+stylesheets/sources/admin/source_1.scss
+stylesheets/sources/admin/source_2.scss
+stylesheets/sources/application/source_1.scss
+stylesheets/sources/application/source_2.scss
+```
+
+Then adjust the `build` attribute in `package.json`:
+```
+"build:css": "sass ./app/assets/stylesheets/entrypoints:./app/assets/builds --no-source-map --load-path=node_modules"
+```
+
+### Deprecation warnings
+
+Sass might raise deprecation warnings depending on what features you are using (such as division), but the messages will explain how to fix them. If you are not sure, see more details in the [official documentation](https://sass-lang.com/documentation/breaking-changes).
+
+## 3. Migrate from Sprockets to Propshaft
+
+Start by following these steps:
+
+1. Remove `sprockets`, `sprockets-rails`, and `sass-rails` from the Gemfile and add `propshaft`;
+2. Run `./bin/bundle install`;
+3. Check your `Gemfile.lock`, repeat steps 1 and 2 for gems that list `sprockets` or `sprockets-rails` as a dependency;
+4. Open `config/application.rb` and remove `config.assets.paths << Rails.root.join('app','assets')`;
+5. Remove `app/assets/config/manifest.js`.
+6. Replace all asset_helpers (`image_url`, `font_url`) in css files with standard `urls`.
+7. If you are importing only the frameworks you need (instead of `rails/all`), remove `require "sprockets/railtie"`;
+
+### Asset paths
+
+Propshaft will automatically include in its search paths the folders `vendor/assets`, `lib/assets` and `app/assets` of your project and of all the gems in your Gemfile. You can see all included files by using the `reveal` rake task:
+```
+ rake assets:reveal
+```
+
+### Asset helpers
+
+Propshaft does not rely on asset_helpers (`asset_path`, `asset_url`, `image_url`, etc.) like Sprockets did. Instead, it will search for every `url` function in your css files, and adjust them to include the digest of the assets they reference.
+
+Go through your css files, and make the necessary adjustments:
+```diff
+- background: image_url('hero.jpg');
++ background: url('/hero.jpg');
+```
+
+Notice that Propshaft's version starts with an `/` and Sprockets' version does not? That's because the latter uses **absolute paths**, and the former uses **relative paths**. To better illustrate that difference, let's assume you have the following structure:
+
+```
+assets/stylesheets/theme/main.scss
+assets/images/hero.jpg
+```
+
+In Sprockets, `main.scss` can reference `hero.jpg` like this:
+```css
+background: image_url('hero.jpg')
+```
+
+Using the same path with `url` in Propshaft will cause it to raise an error, saying it cannot locate `theme/hero.jpg`. That's because Propshaft assumes all paths are relative to the path of the file it's processing. Since it was processing a css file inside the `theme` folder, it will also look for `hero.jpg` in the same folder.
+
+By adding a `/` at the start of the path we are telling Propshaft to consider this path as an absolute path. While this change in behavior increases the work a bit when upgrading, it makes **external libraries like FontAwesome and Bootstrap themes work out-of-the-box**.  
+
+### Asset content
+
+It's a common pattern in apps to inline small SVG files and low resolution versions of images that need to be displayed as quickly as possible. In Propshaft, the same line of code works for all environments: 
+```ruby
+Rails.application.assets.load_path.find('logo.svg').content
+```
+
+As Rails escapes html tags in views by default, in order to output a rendered svg you will need to specify rails not to escape the string using [html_safe](https://api.rubyonrails.org/classes/String.html#method-i-html_safe) or [raw](https://api.rubyonrails.org/classes/ActionView/Helpers/OutputSafetyHelper.html#method-i-raw).
+```ruby
+Rails.application.assets.load_path.find('logo.svg').content.html_safe
+raw Rails.application.assets.load_path.find('logo.svg').content
+```
+
+### Precompilation in development
+
+Propshaft uses a dynamic assets resolver in development mode. However, when you run `assets:precompile` locally Propshaft will then switch to a static assets resolver. Therefore, changes to assets will not be observed anymore and you will have to precompile the assets each time changes are made. This is different to Sprockets.
+
+If you wish to have dynamic assets resolver enabled again, you need to clean your target folder (usually `public/assets`) and propshaft will start serving dynamic content from source.  One way to do this is to run `rails assets:clobber`.
+
+Another way to watch changes in your CSS & JS assets is by running `bin/dev` command instead of `rails server` that not only runs the server but also keeps looking for any changes in the assets and once it detects any changes, it compiles them while the server is running. This is possible because of the `Procfile.dev`.
+
+## 4. Specific Configuration for Test Environments
+
+### Understanding Propshaft's Test Mode
+
+Propshaft automatically configures itself for test environments with these defaults:
+
+```ruby
+# Automatically enabled in test environment
+config.assets.server = Rails.env.test?  # true for test environment
+config.assets.sweep_cache = false       # Disabled for faster tests
+```
+
+### Test Environment Configuration
+
+```ruby
+# config/environments/test.rb
+Rails.application.configure do
+  # Asset server is automatically enabled - no precompilation needed
+  config.assets.server = true
+  
+  # Optional: Add test-specific asset paths
+  config.assets.paths << Rails.root.join('spec/fixtures/assets')
+  
+  # Optional: Disable SRI for faster test execution
+  config.assets.integrity_hash_algorithm = nil
+  
+  # Optional: Customize asset prefix for isolated testing
+  # config.assets.prefix = '/test-assets'
+  
+  # Performance: Use faster file watcher (if using listen gem)
+  config.file_watcher = ActiveSupport::EventedFileUpdateChecker
+end
+```
+
+### Testing Asset Integration
+
+#### RSpec Configuration
+
+```ruby
+# spec/rails_helper.rb
+RSpec.configure do |config|
+  # Ensure assets are available in feature specs
+  config.before(:suite) do
+    # Warm up asset cache for faster test execution
+    Rails.application.assets.load_path.assets
+  end
+  
+  # Clean up assets between tests if needed
+  config.after(:each) do
+    # Only if you modify asset paths during tests
+    # Rails.application.assets.load_path.clear_cache
+  end
+end
+```
+
+#### Testing Asset Helpers
+
+```ruby
+# spec/helpers/application_helper_spec.rb
+RSpec.describe ApplicationHelper, type: :helper do
+  describe "asset helpers" do
+    it "resolves asset paths correctly" do
+      expect(helper.asset_path('application.js')).to match(%r{^/assets/application-\w+\.js$})
+    end
+    
+    it "includes integrity hashes when configured" do
+      allow(Rails.application.config.assets).to receive(:integrity_hash_algorithm).and_return('sha384')
+      result = helper.javascript_include_tag('application', integrity: true)
+      expect(result).to include('integrity="sha384-')
+    end
+  end
+end
+```
+
+#### Feature Spec Asset Testing
+
+```ruby
+# spec/features/assets_spec.rb
+RSpec.describe "Asset loading", type: :feature do
+  it "serves JavaScript assets correctly" do
+    visit root_path
+    expect(page).to have_css('script[src*="/assets/application-"]')
+  end
+  
+  it "serves CSS assets correctly" do
+    visit root_path  
+    expect(page).to have_css('link[href*="/assets/application-"][rel="stylesheet"]')
+  end
+end
+```
+
+### Common Test Environment Issues and Solutions
+
+#### Issue 1: Assets Not Found in Tests
+**Symptom**: `Propshaft::MissingAssetError` in test environment
+**Solution**:
+```ruby
+# Ensure asset server is enabled in test.rb
+config.assets.server = true
+
+# Check that build artifacts exist
+# For jsbundling-rails/cssbundling-rails:
+bundle exec rake assets:precompile  # If assets need building
+```
+
+#### Issue 2: Slow Test Startup
+**Symptom**: Tests take long to start due to asset discovery
+**Solution**:
+```ruby
+# config/environments/test.rb
+# Disable sweep_cache (should be default)
+config.assets.sweep_cache = false
+
+# Exclude unnecessary paths
+config.assets.excluded_paths += [
+  Rails.root.join("app/assets/stylesheets"),  # If using cssbundling
+  Rails.root.join("app/javascript")           # If using jsbundling
+]
+```
+
+#### Issue 3: Inconsistent Asset Paths Between Environments
+**Symptom**: Tests pass but development/production fails with asset references
+**Solution**:
+```ruby
+# Use consistent asset path helpers across environments
+# In views, always use:
+<%= asset_path('image.png') %>        # Good
+# Instead of:
+"/assets/image.png"                   # Bad - won't work with digests
+```
+
+### Performance Optimization for Tests
+
+#### Precompile Once Strategy
+For CI/CD environments where you can precompile once:
+
+```bash
+# In CI setup
+bundle exec rake assets:precompile
+RAILS_ENV=test bundle exec rspec
+```
+
+#### Asset Path Caching
+```ruby
+# config/initializers/assets.rb (test environment)
+if Rails.env.test?
+  # Warm asset cache on initialization to avoid repeated discovery
+  Rails.application.config.after_initialize do
+    Rails.application.assets.load_path.assets
+  end
+end
+```
+
+### Integration with Test Coverage Tools
+
+#### SimpleCov Configuration
+```ruby
+# spec/spec_helper.rb
+require 'simplecov'
+SimpleCov.start 'rails' do
+  # Exclude built assets from coverage
+  add_filter 'app/assets/builds/'
+  add_filter 'vendor/assets/'
+end
+```
+
+### Docker and Containerized Testing
+
+#### Dockerfile Considerations
+```dockerfile
+# Dockerfile
+FROM ruby:3.2
+
+# Install Node.js for asset building
+RUN curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
+RUN apt-get install -y nodejs
+
+# Install dependencies
+COPY Gemfile Gemfile.lock package.json package-lock.json ./
+RUN bundle install && npm install
+
+# Copy source
+COPY . .
+
+# Build assets once for all test runs
+RUN bundle exec rake assets:precompile
+
+# Run tests
+CMD ["bundle", "exec", "rspec"]
+```
+
+### Migration Testing Strategy
+
+#### Before/After Asset Comparison
+```ruby
+# spec/migration/sprockets_to_propshaft_spec.rb
+RSpec.describe "Sprockets to Propshaft migration" do
+  let(:expected_assets) do
+    %w[application.js application.css logo.png favicon.ico]
+  end
+  
+  it "serves all expected assets" do
+    expected_assets.each do |asset|
+      expect(Rails.application.assets.resolver.resolve(asset)).to be_present
+    end
+  end
+  
+  it "maintains asset content integrity" do
+    # Test that specific assets contain expected content
+    asset = Rails.application.assets.load_path.find('application.js')
+    expect(asset.content).to include('expected_javascript_content')
+  end
+end
+```
+
+This comprehensive guide covers the complete migration from Sprockets to Propshaft with special attention to test environment configuration and common pitfalls.