Make clear that the enum array should not be changed once defined. [ci skip]

1 files changed, 12 insertions, 1 deletions

diff --git a/activerecord/lib/active_record/enum.rb b/activerecord/lib/active_record/enum.rb
index 5fcc0382d8..34c17f11a9 100644
--- a/activerecord/lib/active_record/enum.rb
+++ b/activerecord/lib/active_record/enum.rb
@@ -26,12 +26,23 @@ module ActiveRecord
   #
   # Good practice is to let the first declared status be the default.
   #
-  # Finally, it's also possible to explicitly map the relation between attribute and database integer:
+  # Finally, it's also possible to explicitly map the relation between attribute and
+  # database integer with a +Hash+:
   #
   #   class Conversation < ActiveRecord::Base
   #     enum status: { active: 0, archived: 1 }
   #   end
   #
+  # Note that when an +Array+ is used, the implicit mapping from the values to database
+  # integers is derived from the order the values appear in the array. In the example,
+  # <tt>:active</tt> is mapped to +0+ as it's the first elemet, and <tt>:archived</tt>
+  # is mapped to +1+. In general, the +i+-th element is mapped to <tt>i-1</tt> in the
+  # database.
+  #
+  # Therefore, once a value is added to the enum array, its position in the array must
+  # be maintained, and new values should only be added to the end of the array. To
+  # remove unused values, the explicit +Hash+ syntax should be used.
+  #
   # In rare circumstances you might need to access the mapping directly.
   # The mappings are exposed through a constant with the attributes name:
   #