Rails Engine Compatibility

Core principle: Every claimed Rails/Ruby version must be in the CI matrix. Prefer explicit support targets over accidental compatibility.

HARD-GATE

Before claiming support for a Rails/Ruby version:
  1. bundle exec rake zeitwerk:check        # verify autoloading on each version
  2. bundle exec rspec                       # full suite per matrix version
  3. CI matrix must pass — not just main Rails version

DO NOT ship compatibility changes without verifying both autoloading and full suite.

Quick Reference

Core Checks

1. Define supported Ruby and Rails versions — state them in gemspec and README.
2. Run bundle exec rake zeitwerk:check — file paths must match constant names exactly.
3. Check initializer behavior across boot and reload — use config.to_prepare for reload-sensitive hooks.
4. Verify gemspec dependency bounds match tested versions: spec.add_dependency "rails", ">= 7.0", "< 8.0" — bounds must match what CI actually tests.
5. Check optional integrations (jobs, mailers, assets, routes) per version.
6. CI matrix must run against each claimed Rails/Ruby combination:

strategy:
  matrix:
    include:
      - { ruby: "3.2", rails: "7.1" }
      - { ruby: "3.3", rails: "7.2" }

Pitfalls

Key Example: Feature Detection

# ❌ Bad — brittle, wrong for patch versions
if Rails.version >= "7.0"
  config.active_support.cache_format_version = 7.0
end

# ✅ Good — detect the capability directly
if ActiveSupport::Cache.respond_to?(:format_version=)
  config.active_support.cache_format_version = 7.0
end

See EXAMPLES.md for gemspec bounds, Zeitwerk file/constant naming, reload-safe hooks, and CI matrix YAML.

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