upgrade-engine

Upgrade Engine

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.

Core Process

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 (e.g. my_engine/widget_policy.rb → MyEngine::WidgetPolicy).
3. Check initializer behavior across boot and reload — use config.to_prepare for reload-sensitive hooks; hooks placed at load time are reload-unsafe in development.
4. Verify gemspec dependency bounds match tested versions: spec.add_dependency "rails", ">= 7.0", "< 8.0" — bounds must reflect what CI actually tests. Unbounded or overclaiming constraints (>= 5.2 without testing 5.2/6.x) are silent incompatibilities.
5. Replace Rails.version branching with feature detection — version checks are brittle across patch releases:

# ❌ 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

1. Check optional integrations (jobs, mailers, assets, routes, install generators, dummy-app mounts) per version. State the check even if an integration is absent.
2. 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" }

Extended Resources

• assets/compatibility_matrix.md
• assets/zeitwerk_notes.md
• EXAMPLES.md