byebug incompatible with Rails 6.0 defaults, but still recommended in edge docs

[markokajzer]

Steps to reproduce

The Rails guides have a nice section about debugging, including some instructions on how to use the byebug gem, see https://edgeguides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-byebug-gem.

Rails 6+ also comes with Zeitwerk mode enabled by default as per documentation. Unfortunately, this is actually incompatible with the byebug gem, as mentioned in the Zeitwerk docs. It also does not seem to be an easy issue to resolve in the near future, see here.

This is a bit unfortunate, as the guides should provide valid documentation for Rails running on the defaults.

What is the current debugging solution for Rails? Did everybody just switch to the break gem? We tried to switch over, but had some problems with it as well. byebug is such a big thing in the Ruby / Rails community from our experience that we did not expect this to break when switching to Zeitwerk 😄

Expected behavior

Guides work with current Rails defaults

Actual behavior

byebug debugging incompatible with Zeitwerk which is enabled by default in Rails 6

[byroot]

Ruby will soon have an official debugger again: https://bugs.ruby-lang.org/issues/17863 / https://github.com/ruby/debug

It's still prerelease for now, but I tested it, it works pretty well and play nice with Zeitwerk.

I haven't tested break much, but I think we can just wait a bit for debug 1.0.0 to come out and update the docs then.

[byroot]

Ah and to clarify, the bug is a little annoying but it's not "fully broken". I still use byebug daily. The bug is easy to workaround by referencing the autoloaded constants you need before the breakpoint. Definitely not ideal, but depending on what you are doing, some people might have never noticed that bug.

[zzak]

@byroot could you provide an example? I don't think we know when to expect debug to be stable enough to recommend it. In the mean time, this seems like an issue more people could experience even if it's not directly affecting Rails.

[byroot]

@byroot could you provide an example?

Of how to workaround the autoloading issue?

The issue arise in this kind of cases:

byebug
Some::NotYetLoaded::Constant.foo

You can do instead:

Some::NotYetLoaded::Constant # trigger the constant loading before the breakpoint
byebug
Some::NotYetLoaded::Constant.foo

Of course in some case you are very early in the load cycle so it's not practical.

I don't think we know when to expect debug to be stable enough to recommend it

Indeed, so maybe we could first update the doc to recommend break, but debug will be embeded with Ruby 3.1, so whenever it's out we should update the docs to recommend that one instead.

[byroot]

cc @fxn since I just heard you had plans about this.

[fxn]

Thanks Jean!

[zzak]

Ok, I'm getting caught up on break and will work on updating the guide to use that instead.

We should be able to replace it with a guide for debug whenever that is production ready.

[fxn]

Thanks @zzak.

Wait a bit though, it is possible that we just do not include a debugger in the generated Gemfile.

[eregon]

I wonder if it would be possible to adapt byebug to avoid the nested TracePoint problem: deivid-rodriguez/byebug#564 (comment)

[markokajzer]

Wait a bit though, it is possible that we just do not include a debugger in the generated Gemfile

Probably the easiest way out, but the question still stands... How to debug Rails 6 apps? I feel like it's not the Ruby way to just remove the debugging section from the docs and leave fellow devs to it 😄

[fxn]

@markokajzer The way to edit the docs depends on the final decision about the default Gemfile, but something will be said one way or another.

[fxn]

The team decision has been to bet on the new debugger that is going to ship with CRuby.

As soon as version 1.0 is released, I'll patch the generated Gemfile, update docs, etc., and will close here.

[fxn]

Fixed in 89801b2.

That guide had basically a tutorial on using byebug. I believe we do not have to repeat the documentation of other software. The guide points you to ruby/debug, and ruby/debug is the one that tells you how to use it.