Document behaviour shipping in 4.5.0

docs/docs/getting-started/configuration.md

@@ -59,7 +59,21 @@ if there are two searches on one page. Another name may be set using the `search
 
 ### In the view
 
+The form helpers read the key from the search object, so nothing extra is
+needed:
+
 ```erb
-<%= f.search_form_for @search, as: :log_search %>
+<%= search_form_for @search %>
 <%= sort_link(@search) %>
 ```
+
+This emits `log_search[...]` field names rather than the default `q[...]`.
+
+:::note
+
+Before Ransack 5.0 the form helpers ignored a per-search `search_key` and always
+used the global default, so the key had to be repeated as `as: :log_search`
+(`scope:` for `search_form_with`). Passing it explicitly still works and still
+wins. See [#1118](https://github.com/activerecord-hackery/ransack/issues/1118).
+
+:::

docs/docs/getting-started/search-matches.md

@@ -66,3 +66,24 @@ List of all possible predicates
 
 
 See full list: https://github.com/activerecord-hackery/ransack/blob/main/lib/ransack/locale/en.yml#L16
+
+### Searching `enum` attributes
+
+An Active Record `enum` can be searched by its label rather than its underlying
+value. Ransack casts the label before building the query:
+
+```ruby
+class Person < ApplicationRecord
+  enum :temperament, { sanguine: 1, choleric: 2, melancholic: 3, phlegmatic: 4 }
+end
+
+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)
+```
+
+This means a select built from `Person.temperaments.keys` can be posted
+straight back to Ransack without translating the labels yourself.
+

docs/docs/going-further/other-notes.md

@@ -232,6 +232,18 @@ class Article < ActiveRecord::Base
 end
 ```
 
+The allowlists may be given as strings or as symbols — `%w[title body]` and
+`%i[title body]` behave identically.
+
+:::note
+
+Before Ransack 5.0 a symbol allowlist was compared against strings without
+normalising, so `%i[title body]` matched nothing and every search on those
+attributes was silently ignored. See
+[#1538](https://github.com/activerecord-hackery/ransack/issues/1538).
+
+:::
+
 Here is example code for the `articles_controller`:
 
 ```ruby