Add changelog and upgrading notice related to I18n enforce_available_locales handling

2 files changed, 30 insertions, 5 deletions

diff --git a/activesupport/CHANGELOG.md b/activesupport/CHANGELOG.md
index 6a13db346d..c830ee61e6 100644
--- a/activesupport/CHANGELOG.md
+++ b/activesupport/CHANGELOG.md
@@ -1,3 +1,16 @@
+*   Default the new `I18n.enforce_available_locales` config to `true`, meaning
+    `I18n` will make sure that all locales passed to it must be declared in the
+    `available_locales` list.
+
+    To disable it add the following configuration to your application:
+
+        config.i18n.enforce_available_locales = false
+
+    This also ensures I18n configuration is properly initialized taking the new
+    option into account, to avoid their deprecations while booting up the app.
+
+    *Carlos Antonio da Silva*, *Yves Senn*
+
 *   Introduce Module#concerning: a natural, low-ceremony way to separate
     responsibilities within a class.
 
@@ -49,11 +62,6 @@
 
     *Mario Visic*
 
-*   Ensure `config.i18n.enforce_available_locales` is set before any other
-    configuration option.
-
-    *Yves Senn*
-
 *   Added `Date#all_week/month/quarter/year` for generating date ranges.
 
     *Dmitriy Meremyanin*
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index ca5623bf73..1c233b4d82 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -156,6 +156,23 @@ end
 ActiveRecord::FixtureSet.context_class.send :include, FixtureFileHelpers
 ```
 
+### I18n enforcing available locales
+
+Rails 4.1 now defaults the I18n option `enforce_available_locales` to `true`,
+meaning that it will make sure that all locales passed to it must be declared in
+the `available_locales` list.
+
+To disable it (and allow I18n to accept *any* locale option) add the following
+configuration to your application:
+
+```ruby
+config.i18n.enforce_available_locales = false
+```
+
+Note that this option was added as a security measure, to ensure user input could
+not be used as locale information unless previously known, so it's recommended not
+to disable this option unless you have a strong reason for doing so.
+
 Upgrading from Rails 3.2 to Rails 4.0
 -------------------------------------