Add debugging docs #6387

mercedesb · 2023-02-16T18:07:58Z

What was the end-user or developer problem that led to this PR?

Figuring out how to set up test cases and debug for a new maintainer is hard and there aren't existing docs to refer to. I had a call with @indirect and he walked me through how he debugs the Bundler code. This doc is a starting point for how to debug various test cases.

What is your fix for the problem, implemented in this PR?

Add DEBUGGING.md to document how to debug Bundler

Make sure the following tasks are checked

Describe the problem / feature
Write tests for features and bug fixes
Write code to solve the problem
Make sure you follow the current code style and write meaningful commit messages without tags

simi · 2023-02-16T18:23:07Z

🤔 Usually I just put binding.irb in test and run that one test file or case individually. For integration testing I just run ruby setup.rb to install dev version locally or even run ruby -Ilib bin/gem locally to test gem command.

simi · 2023-02-16T18:24:09Z

bundler/doc/development/DEBUGGING.md

+gem 'tiny_css'
+```
+
+Put a `binding.pry` anywhere you want the debugger to break. Run your Bundler shell alias.


Any reason to recommend binding.pry instead of "native" binding.irb?

Because binding.irb is a REPL and not a debugger 🤷‍♀️ It's nice, but you can't really interactive debug. I can add that to these docs as a tool to use though

It might be worth noting that you need pry-byebug installed to get a full debugger rather than just a pry REPL. 👍🏻

ahhh, good call out. I forget what gems I have installed globally

That's it. Some info is at https://github.com/rubygems/rubygems/blob/030e285881ac99608fe8a23121b80ce1ce14ed6e/bundler/doc/development/SETUP.md#debugging-with-pry. Instead of this "complex" setup, you can do just binding.irb and you have basic IRB-like console. For debug console, you can use binding.break (you need to require 'debug' somehow from debug gem, which is distributed with Ruby if I remember well and there is no need to install additional dependency).

I prefer to prefer "native" Ruby tools :)

Unfortunately, the debug gem was not included until Ruby 3.1, and we will be stuck supporting older rubies for some time still. Ruby 2.7 is not EOL until March 31 2023, and 3.0 is not EOL for another year after that.

I think it is valuable to document a debug gem workflow for the future, but we need tools to allow debugging older rubies for at least the next 1-2 years. 👍🏻

You can install debug gem the same way you can install pry-byebug for older Rubies. It supports Ruby 2.6+.

Anyway the whole discussion is good sign that this setup is not simple. Experienced developers can use their favourite tools, there is almost nothing specific. And for beginners it would be maybe better to point to some generic Ruby debugging tutorial where basics like puts debugging and real debuggers are explained. 🤔

On the other way, if you think @indirect this kind of guide is valuable in here, let's start somewhere. I'm ok with anything that works. I was just about share my experience.

Based on this convo, I reorganized the doc slightly and tried to add just enough info to get new maintainers started but would like to link out to other places for more learning. Do we care who/what we link to? Here are some options (not in the doc yet)

REPL debugging more info: https://st0012.dev/whats-new-in-ruby-3-2-irb

Prints debugging more info: https://medium.com/@calielrushton/puts-prints-and-more-printing-to-the-console-in-ruby-7830cdaace0a

Interactive debugging more info: https://github.com/ruby/debug#how-to-use

deivid-rodriguez

I added a couple of comments. Debugging tips never hurt, thanks for documenting this!

deivid-rodriguez · 2023-02-16T18:26:45Z

bundler/doc/development/DEBUGGING.md

+
+## Debugging in tests
+
+Your best option is to print debug in the test suite. Put `puts` statements anywhere you want to see an object or variable and you'll see your `puts` in the console output.


I mainly use puts debugging too! Sometimes printing caller_locations(0).join("\n") helps to see what the stacktrace is at a given point.

Wonderful, I'll add that to the list of examples

deivid-rodriguez · 2023-02-16T18:29:03Z

bundler/doc/development/DEBUGGING.md

+```bash
+cd tmp
+mkdir [name of directory for local testing] && cd [name of directory for local testing]
+dbundle init


I normally point directly to my working copy with something like /path/to/rubygems/bundle/exe/bundle. These days once you land on a copy of Bundler, you never get out of it because we always use require_relative, so messing with the $LOAD_PATH should not be necessary.

Ah so should we change the alias instructions in the setup doc?

I don't mind the current recommendation to set an alias, and it should also work just fine, I don't think you need to change anything. Just wanted to mention the way I do it :)

I think everyone have different debugging habits :). I was using ruby -Ilib -s ./exe/bundle -- --version and even today it is usually enough to just call ./exe/bundle.

But indeed, dbundle is mentioned at various places. It is ok to keep it in here as well.

mercedesb · 2023-02-16T19:56:30Z

For integration testing I just run ruby setup.rb to install dev version locally or even run ruby -Ilib bin/gem locally to test gem command.

I normally point directly to my working copy with something like /path/to/rubygems/bundle/exe/bundle

It sounds like there are multiple ways to test locally which don't match up with what we currently recommend to new maintainers in SETUP.md. Is the alias a totally bad idea? And should we update that doc too?

simi · 2023-02-22T22:21:31Z

bundler/doc/development/DEBUGGING.md

+
+To use REPL, place a `binding.irb` wherever you'd like to take a look around. An interactive `irb` console will open when your code gets to your breakpoint.
+
+To learn more about using IRB, [TODO: link to doc]


Maybe https://github.com/ruby/irb#the-bindingirb-breakpoint?

Add debugging docs (cherry picked from commit 9101d15)

simi reviewed Feb 16, 2023

View reviewed changes

deivid-rodriguez reviewed Feb 16, 2023

View reviewed changes

simi reviewed Feb 22, 2023

View reviewed changes

simi approved these changes Feb 22, 2023

View reviewed changes

hsbt enabled auto-merge March 17, 2023 04:23

hsbt force-pushed the mb-debugging-docs branch 2 times, most recently from 224bd3b to d0c9b01 Compare March 17, 2023 05:55

auto-merge was automatically disabled March 17, 2023 07:35
Merge queue setting changed

hsbt enabled auto-merge March 17, 2023 07:57

hsbt added this pull request to the merge queue Mar 17, 2023

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Mar 17, 2023

mercedesb added 6 commits March 17, 2023 17:57

add debugging docs

0195f4b

add link to debugging from doc readme

d9a7f78

fix spelling

fad5514

add another puts example

d94c722

update debugging docs based on feedback

e498027

fix EOL spacing

48aa283

hsbt force-pushed the mb-debugging-docs branch from d0c9b01 to 48aa283 Compare March 17, 2023 08:57

hsbt enabled auto-merge March 17, 2023 08:57

hsbt added this pull request to the merge queue Mar 17, 2023

Merged via the queue into master with commit 9101d15 Mar 17, 2023

hsbt deleted the mb-debugging-docs branch March 17, 2023 12:39

deivid-rodriguez added the bundler: documentation label Mar 20, 2023

deivid-rodriguez pushed a commit that referenced this pull request Mar 20, 2023

Merge pull request #6387 from rubygems/mb-debugging-docs

195b1ab

Add debugging docs (cherry picked from commit 9101d15)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add debugging docs #6387

Add debugging docs #6387

mercedesb commented Feb 16, 2023

simi commented Feb 16, 2023

simi Feb 16, 2023

mercedesb Feb 16, 2023

indirect Feb 16, 2023

mercedesb Feb 16, 2023

simi Feb 16, 2023 •

edited

indirect Feb 16, 2023

simi Feb 16, 2023

mercedesb Feb 16, 2023

deivid-rodriguez left a comment

deivid-rodriguez Feb 16, 2023

mercedesb Feb 16, 2023

deivid-rodriguez Feb 16, 2023

mercedesb Feb 16, 2023

deivid-rodriguez Feb 16, 2023

simi Feb 22, 2023

mercedesb commented Feb 16, 2023

simi Feb 22, 2023


		## Debugging in tests

		Your best option is to print debug in the test suite. Put `puts` statements anywhere you want to see an object or variable and you'll see your `puts` in the console output.


		To use REPL, place a `binding.irb` wherever you'd like to take a look around. An interactive `irb` console will open when your code gets to your breakpoint.

		To learn more about using IRB, [TODO: link to doc]

Add debugging docs #6387

Add debugging docs #6387

Conversation

mercedesb commented Feb 16, 2023

What was the end-user or developer problem that led to this PR?

What is your fix for the problem, implemented in this PR?

Make sure the following tasks are checked

simi commented Feb 16, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

simi Feb 16, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

deivid-rodriguez left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mercedesb commented Feb 16, 2023

Choose a reason for hiding this comment

simi Feb 16, 2023 •

edited