Deprecate defining enums with keywords args

Enums have historically been defined using keyword arguments:

```ruby
class Function > ApplicationRecord
  enum color: [:red, :blue],
       type: [:instance, :class],
       _scopes: false
```

This has the advantage of being able to define multiple enums at once
with the same options. However, it also has a downside that enum options
must be prefixed with an underscore to separate them from the enum
definitions (to enable models to have enums with the same name as an
option).

In Rails 7, a new syntax was [introduced][1] to instead define enums with
positional arguments:

```ruby
class Function > ApplicationRecord
  enum :color, [:red, :blue], scopes: false
  enum :type, [:instance, :class], scopes: false
```

This new syntax eliminates the need to prefix options with an underscore,
and the docs were updated to recommend this new syntax.

However, both versions of the API have been supported since, and it has
started to cause some problems:

The first issue is that the available options have drifted. In Rails
7.1, an option was added to make assigning an invalid enum value use
validation errors instead of runtime errors. However, the equivalent
underscored prefix option was not added for the original enum syntax

Articles have been created that describe the new option in Rails 7.1,
but the examples in the articles use un-prefixed options with the old
syntax. This confusion has also lead to issues opened asking why that
incorrect syntax is not working.

Additionally, the presence of underscored options is just generally
confusing because it tends to imply an option is for internal use.

This commit aims to fix all of these issues by deprecating the old enum
syntax. With only one way to define enums, options cannot drift and
there will be less confusion around how enums should be defined.

[1]: 0618d2d

Author: skipkayhil

activerecord/CHANGELOG.md

@@ -1,3 +1,19 @@
+*   Deprecate defining an `enum` with keyword arguments.
+
+    ```ruby
+    class Function > ApplicationRecord
+      # BAD
+      enum color: [:red, :blue],
+           type: [:instance, :class]
+
+      # GOOD
+      enum :color, [:red, :blue]
+      enum :type, [:instance, :class]
+    end
+    ```
+
+    *Hartley McGuire*
+
 *   Add `active_record.config.validate_migration_timestamps` option for validating migration timestamps.
 
     When set, validates that the timestamp prefix for a migration is no more than a day ahead of

activerecord/lib/active_record/enum.rb

@@ -223,6 +223,13 @@ def enum(name = nil, values = nil, **options)
       options.transform_keys! { |key| :"#{key[1..-1]}" }
 
       definitions.each { |name, values| _enum(name, values, **options) }
+
+      ActiveRecord.deprecator.warn(<<~MSG)
+        Defining enums with keyword arguments is deprecated and will be removed
+        in Rails 7.3. Positional arguments should be used instead:
+
+        #{definitions.map { |name, values| "enum :#{name}, #{values}" }.join("\n")}
+      MSG
     end
 
     private

activerecord/test/cases/associations/has_many_associations_test.rb

@@ -486,7 +486,7 @@ class SpecialBook < ActiveRecord::Base
     self.table_name = "books"
 
     belongs_to :author
-    enum last_read: { unread: 0, reading: 2, read: 3, forgotten: nil }
+    enum :last_read, { unread: 0, reading: 2, read: 3, forgotten: nil }
   end
 
   def test_association_enum_works_properly

activerecord/test/cases/associations/has_one_associations_test.rb

@@ -807,7 +807,7 @@ class SpecialBook < ActiveRecord::Base
     belongs_to :author, class_name: "SpecialAuthor"
     has_one :subscription, class_name: "SpecialSubscription", foreign_key: "subscriber_id"
 
-    enum status: [:proposed, :written, :published]
+    enum :status, [:proposed, :written, :published]
   end
 
   class SpecialAuthor < ActiveRecord::Base

activerecord/test/cases/attribute_methods_test.rb

@@ -1381,7 +1381,8 @@ class ChildWithDeprecatedBehaviorResolved < ClassWithDeprecatedAliasAttributeBeh
     self.table_name = "books"
 
     attribute :status, :string
-    enum status: {
+
+    enum :status, {
       pending: "0",
       completed: "1",
     }