From e6b286f9baca7c6c97c90288acdd563c40d5103f Mon Sep 17 00:00:00 2001
From: Xavier Noria <fxn@hashref.com>
Date: Mon, 6 Dec 2021 12:42:39 +0100
Subject: [PATCH] Revise docs/comments for the debug gem

---
 guides/source/debugging_rails_applications.md | 29 +++++++++++++++++++
 .../generators/rails/app/templates/Gemfile.tt |  8 +----
 2 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/guides/source/debugging_rails_applications.md b/guides/source/debugging_rails_applications.md
index d47406d5bd..70165b8bc6 100644
--- a/guides/source/debugging_rails_applications.md
+++ b/guides/source/debugging_rails_applications.md
@@ -470,6 +470,35 @@ class variables: @@raise_on_missing_translations  @@raise_on_open_redirects
 
 You can find more commands and configuration options from its [documentation](https://github.com/ruby/debug).
 
+#### Autoloading Caveat
+
+Debugging with `debug` works fine most of the time, but there's an edge case: If you evaluate an expression in the console that autoloads a namespace defined in a file, constants in that namespace won't be found.
+
+For example, if the application has these two files:
+
+```ruby
+# hotel.rb
+class Hotel
+end
+
+# hotel/pricing.rb
+module Hotel::Pricing
+end
+```
+
+and `Hotel` is not yet loaded, then
+
+```
+(rdbg) p Hotel::Pricing
+```
+
+will raise a `NameError`. In some cases, Ruby will be able to resolve an unintended constant in a different scope.
+
+If you hit this, please restart your debugging session with eager loading enabled (`config.eager_load = true`).
+
+Stepping commands line `next`, `continue`, etc., do not present this issue. Namespaces defined implictly only by subdirectories are not subject to this issue either.
+
+See [ruby/debug#408](https://github.com/ruby/debug/issues/408) for details.
 
 Debugging with the `web-console` gem
 ------------------------------------
diff --git a/railties/lib/rails/generators/rails/app/templates/Gemfile.tt b/railties/lib/rails/generators/rails/app/templates/Gemfile.tt
index 4caa0d8e98..abb5432d0f 100644
--- a/railties/lib/rails/generators/rails/app/templates/Gemfile.tt
+++ b/railties/lib/rails/generators/rails/app/templates/Gemfile.tt
@@ -44,13 +44,7 @@ gem "bootsnap", ">= 1.4.4", require: false
 <% if RUBY_ENGINE == "ruby" -%>
 
 group :development, :test do
-  # Writing `binding.irb` in a spot to debug gives you a console. If the project
-  # depends on Pry, `binding.pry` is also available. For them to work, you don't
-  # need to depend on the `debug` gem.
-  #
-  # To get a proper debugger, depend on the `debug` gem and execute `binding.b`.
-  # However, better eager load the application, because `debug` and autoloading
-  # are not fully compatible. See https://github.com/ruby/debug/issues/408.
+  # See https://edgeguides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
   gem "debug", ">= 1.0.0", platforms: %i[ mri mingw x64_mingw ]
 end
 <% end -%>