From 8bae32ba2cb176622d2fed58ec1ef996ec19d855 Mon Sep 17 00:00:00 2001
From: Alberto Almagro <albertoalmagro@gmail.com>
Date: Fri, 1 May 2020 14:35:38 +0200
Subject: [PATCH] Add mention to shared section in `config_for` docs [ci skip]

37913 added the possibility to deeply merge configurations by grouping
them within a shared section. This powerful alternative was not reflected
in any documentation, which made my team think it was not possible until
I found out this feature after looking at the source code.

This patch reflects this change in the documentation so that it is
easier for other developers to know about this behavior.
---
 guides/source/configuring.md      | 25 ++++++++++++++++++++++++-
 railties/lib/rails/application.rb | 21 ++++++++++++++++++++-
 2 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/guides/source/configuring.md b/guides/source/configuring.md
index 2aaece6fef..aa3d75693e 100644
--- a/guides/source/configuring.md
+++ b/guides/source/configuring.md
@@ -1592,13 +1592,14 @@ These configuration points are then available through the configuration object:
 
 You can also use `Rails::Application.config_for` to load whole configuration files:
 
-  ```ruby
+  ```yaml
   # config/payment.yml:
   production:
     environment: production
     merchant_id: production_merchant_id
     public_key:  production_public_key
     private_key: production_private_key
+
   development:
     environment: sandbox
     merchant_id: development_merchant_id
@@ -1616,6 +1617,28 @@ You can also use `Rails::Application.config_for` to load whole configuration fil
   ```ruby
   Rails.configuration.payment['merchant_id'] # => production_merchant_id or development_merchant_id
   ```
+`Rails::Application.config_for` supports a `shared` configuration to group common
+configurations. The shared configuration will be merged into the environment
+configuration.
+
+  ```yaml
+  # config/example.yml
+  shared:
+    foo:
+      bar:
+        baz: 1
+
+  development:
+    foo:
+      bar:
+        qux: 2
+  ```
+
+
+  ```ruby
+  # development environment
+  Rails.application.config_for(:example)[:foo][:bar] #=> { baz: 1, qux: 2 }
+  ```
 
 Search Engines Indexing
 -----------------------
diff --git a/railties/lib/rails/application.rb b/railties/lib/rails/application.rb
index 417019fbfb..864fd63de9 100644
--- a/railties/lib/rails/application.rb
+++ b/railties/lib/rails/application.rb
@@ -206,12 +206,13 @@ def message_verifier(verifier_name)
 
     # Convenience for loading config/foo.yml for the current Rails env.
     #
-    # Example:
+    # Examples:
     #
     #     # config/exception_notification.yml:
     #     production:
     #       url: http://127.0.0.1:8080
     #       namespace: my_app_production
+    #
     #     development:
     #       url: http://localhost:3001
     #       namespace: my_app_development
@@ -220,6 +221,24 @@ def message_verifier(verifier_name)
     #     Rails.application.configure do
     #       config.middleware.use ExceptionNotifier, config_for(:exception_notification)
     #     end
+    #
+    #     # You can also store configurations in a shared section which will be
+    #     # merged with the environment configuration
+    #
+    #     # config/example.yml
+    #     shared:
+    #       foo:
+    #         bar:
+    #           baz: 1
+    #
+    #     development:
+    #       foo:
+    #         bar:
+    #           qux: 2
+    #
+    #     # development environment
+    #     Rails.application.config_for(:example)[:foo][:bar]
+    #     # => { baz: 1, qux: 2 }
     def config_for(name, env: Rails.env)
       yaml = name.is_a?(Pathname) ? name : Pathname.new("#{paths["config"].existent.first}/#{name}.yml")
 
-- 
GitLab