Rails Engine Compatibility

Use this skill when the task is to make an engine stable across framework versions and host environments.

Compatibility work should reduce surprises for host applications. Prefer explicit support targets over accidental compatibility.

Quick Reference

Compatibility Aspect	Check
Zeitwerk	File paths match constant names; no anonymous or root-level constants
Gemspec bounds	add_dependency and required_ruby_version match tested versions
Feature detection	Use respond_to?, defined?, or adapter seams instead of Rails.version
Test matrix	CI runs against each claimed Rails/Ruby combination

Common Mistakes

Mistake	Reality
Hardcoding Rails version checks	Use feature detection or adapter seams; version branching is brittle and often wrong
Missing Zeitwerk compatibility	File paths must match constant names; mismatches break autoloading in Rails 6+
No CI matrix	Claiming support for multiple versions without testing them leads to silent breakage

Red Flags

• No version bounds in gemspec
• Direct Rails.version checks instead of feature detection
• No reload safety for to_prepare or initializer hooks

Core Checks

1. Define supported Ruby and Rails versions.
2. Check autoloading and Zeitwerk expectations.
3. Check initializer behavior across boot and reload.
4. Check dependency bounds in the gemspec.
5. Check optional integrations such as jobs, mailers, assets, and routes.
6. Verify the test matrix matches the claimed support policy.

Important Areas

• Zeitwerk naming and file paths
• deprecated Rails APIs
• middleware or railtie hooks
• engine assets and precompile expectations
• migration compatibility
• configuration defaults that changed between Rails versions

Rules

• Do not claim support for versions that are not tested.
• Keep dependency constraints honest and narrow enough to be meaningful.
• Prefer feature detection or adapter seams over version-specific branching when practical.
• If branching by version is necessary, isolate it and test both paths.

Common Review Findings

• file naming incompatible with Zeitwerk
• broad gemspec constraints without matrix coverage
• deprecated initializer hooks
• assumptions tied to a single asset stack
• tests only on one Rails version while README claims many

Examples

Gemspec version bounds (honest, testable):

# Good: narrow and tested
spec.add_dependency "rails", ">= 7.0", "< 8.0"
spec.required_ruby_version = ">= 3.0"

# Bad: claims support without CI
# spec.add_dependency "rails", ">= 5.2"  # untested on 5.2/6.x

Zeitwerk: file and constant must match:

# File: lib/my_engine/widget_policy.rb
# Good: constant matches path
module MyEngine
  class WidgetPolicy
  end
end

# Bad: will break with Zeitwerk
# class WidgetPolicy  # expected in widget_policy.rb at root

Reload-safe hook:

# In engine.rb
config.to_prepare do
  MyEngine::Decorator.apply  # runs on each reload in dev
end

Output Style

When asked to improve compatibility:

1. State the support matrix being targeted.
2. List the most likely breakpoints.
3. Make compatibility changes in isolated, testable seams.
4. Recommend matrix coverage if it does not exist.

Integration

Skill	When to chain
rails-engine-testing	Test matrix setup, CI configuration, multi-version tests
rails-engine-author	Engine structure, host contract, namespace design
rails-engine-release	Versioning, changelog, upgrade notes for compatibility changes