From 8be0c10c4827ba1e86b69ec47b53f7cbfaad9023 Mon Sep 17 00:00:00 2001
From: Edouard CHIN <chin.edouard@gmail.com>
Date: Fri, 6 Oct 2023 19:07:06 +0200
Subject: [PATCH] Add doc to explain how to migrate to the new BroadcastLogger:

- This should make it easier for apps or libraries that were
  previously relying on the private API.
  Also took the opportunity to tweak the doc of the BroadcastLogger
  to mention what happens when calling a non-standard method.

  Fix #49494
---
 .../lib/active_support/broadcast_logger.rb    | 20 ++++++++++++
 guides/source/upgrading_ruby_on_rails.md      | 32 +++++++++++++++++++
 2 files changed, 52 insertions(+)

diff --git a/activesupport/lib/active_support/broadcast_logger.rb b/activesupport/lib/active_support/broadcast_logger.rb
index 90b1b98c60263..7cdb1c7ae7771 100644
--- a/activesupport/lib/active_support/broadcast_logger.rb
+++ b/activesupport/lib/active_support/broadcast_logger.rb
@@ -51,6 +51,26 @@ module ActiveSupport
   #
   #   broadcast = BroadcastLogger.new
   #   broadcast.info("Hello world") # The log message will appear nowhere.
+  #
+  # If you are adding a custom logger with custom methods to the broadcast,
+  # the `BroadcastLogger` will proxy them and return the raw value, or an array
+  # of raw values, depending on how many loggers in the broadcasts responded to
+  # the method:
+  #
+  #   class MyLogger < ::Logger
+  #     def loggable?
+  #       true
+  #     end
+  #   end
+  #
+  #   logger = BroadcastLogger.new
+  #   logger.loggable? # => A NoMethodError exception is raised because no loggers in the broadcasts could respond.
+  #
+  #   logger.broadcast_to(MyLogger.new(STDOUT))
+  #   logger.loggable? # => true
+  #   logger.broadcast_to(MyLogger.new(STDOUT))
+  #   puts logger.broadcasts # => [MyLogger, MyLogger]
+  #   logger.loggable? # [true, true]
   class BroadcastLogger
     include ActiveSupport::LoggerSilence
 
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index bc2659d238b96..4b0c1d0c7f244 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -281,6 +281,38 @@ ActiveSupport.on_load :action_view_test_case do
 end
 ```
 
+### `Rails.logger` now returns an `ActiveSupport::BroadcastLogger` instance
+
+The `ActiveSupport::BroadcastLogger` class is a new logger that allows to broadcast logs to different sinks (STDOUT, a log file...) in an easy way.
+
+The API to broadcast logs (using the `ActiveSupport::Logger.broadcast` method) was removed and was previously private.
+If your application or library was relying on this API, you need to make the following changes:
+
+```ruby
+logger = Logger.new("some_file.log")
+
+# Before
+
+Rails.logger.extend(ActiveSupport::Logger.broadcast(logger))
+
+# After
+
+Rails.logger.broadcast_to(logger)
+```
+
+If your application had configured a custom logger, `Rails.logger` will wrap and proxy all methods to it. No changes on your side are required to make it work.
+
+If you need to access your custom logger instance, you can do so using the `broadcasts` method:
+
+```ruby
+# config/application.rb
+config.logger = MyLogger.new
+
+# Anywhere in your application
+puts Rails.logger.class #=> BroadcastLogger
+puts Rails.logger.broadcasts #=> [MyLogger]
+```
+
 [assert_match]: https://docs.seattlerb.org/minitest/Minitest/Assertions.html#method-i-assert_match
 
 Upgrading from Rails 6.1 to Rails 7.0