Document behaviour shipping in 4.5.0

[scarroll32]

Note

This PR was opened by Claude (Claude Code), acting on behalf of @scarroll32.

Three changes already merged for 4.5.0 shipped without documentation.

enum support (#1665)

Entirely undocumented — nothing in docs/ mentioned enums at all, so there was no way to know Ransack handles them short of reading the specs. Adds a section to Search Matchers showing that an enum can be searched by label rather than underlying value:

Person.ransack(temperament_eq: 'choleric').result.to_sql
# ... WHERE "people"."temperament" = 2

Person.ransack(temperament_in: ['sanguine', 'choleric']).result.to_sql
# ... WHERE "people"."temperament" IN (1, 2)

which is what makes a select built from Person.temperaments.keys post back cleanly.

Per-search search_key (#1676)

The Configuration page still told readers to write <%= f.search_form_for @search, as: :log_search %> — that as: was the workaround for the bug #1676 fixed. Updated to show the helpers reading the key from the search object, with a note that passing it explicitly still works and still wins.

(The old snippet also had a bug of its own: f.search_form_for rather than search_form_for.)

Symbol allowlists (#1539)

Records that ransackable_attributes and ransackable_associations accept symbols or strings interchangeably — and that before 5.0 a symbol list matched nothing, so searches were silently ignored. That's worth stating explicitly, since the failure mode gave no error.

Verification

Every example was run against the spec schema rather than written from memory — including rendering a real search_form_for through a controller view context to confirm the field names come out as person_search[name_cont].

Note on #1657

While checking examples for this, I found that #1657 (Allow nil values in array) doesn't do what its title suggests for built-in predicates:

Person.ransack(name_in: [nil]).result.to_sql
# => SELECT "people".* FROM "people"        ← no WHERE at all

Person.ransack(name_in: [nil, 'Ernie']).result.to_sql
# => ... WHERE "people"."name" IN ('Ernie') ← nil dropped

The change keeps the parameter alive through Search#initialize, but the built-in in predicate's validator still rejects nil afterwards. It only helps a custom predicate with a permissive validator — which was the author's actual use case in #940. So it's not wrong, just narrower than the title reads, and I've deliberately not documented it as a user-facing feature. Worth wording carefully in the release notes.

🤖 Generated with Claude Code