Merge branch 'tc-pry-docs' into 'master'

First version of pry_debugging.md

Closes #45728

See merge request gitlab-org/gitlab-ce!20740

3 files changed, 132 insertions, 1 deletions

diff --git a/doc/development/README.md b/doc/development/README.md
index 5d6fed5bc72..fed3903c771 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -40,6 +40,7 @@ description: 'Learn how to contribute to GitLab.'
 - [View sent emails or preview mailers](emails.md)
 - [Shell commands](shell_commands.md) in the GitLab codebase
 - [`Gemfile` guidelines](gemfile.md)
+- [Pry debugging](pry_debugging.md)
 - [Sidekiq debugging](sidekiq_debugging.md)
 - [Gotchas](gotchas.md) to avoid
 - [Avoid modules with instance variables](module_with_instance_variables.md) if possible
diff --git a/doc/development/pry_debugging.md b/doc/development/pry_debugging.md
new file mode 100644
index 00000000000..de5e1323e6a
--- /dev/null
+++ b/doc/development/pry_debugging.md
@@ -0,0 +1,130 @@
+# Pry debugging
+
+## Invoking pry debugging
+
+To invoke the debugger, place `binding.pry` somewhere in your
+code. When the Ruby interpreter hits that code, execution will stop,
+and you can type in commands to debug the state of the program
+
+## `byebug` vs `binding.pry`
+
+`byebug` has a very similar interface as `gdb`, but `byebug` does not
+use the powerful Pry REPL.
+
+`binding.pry` uses Pry, but lacks some of the `byebug`
+features. GitLab uses the [`pry-byebug`](https://github.com/deivid-rodriguez/pry-byebug)
+gem. This gem brings some capabilities `byebug` to `binding.pry`, so
+using that, will give you the most debugging powers.
+
+## `byebug`
+
+Check out [the docs](https://github.com/deivid-rodriguez/byebug) for the full list of commands.
+
+You can start the Pry REPL with the `pry` command.
+
+## `pry`
+
+There are **a lot** of features present in `pry`, too much to cover in
+this document, so for the full documentation head over to the [Pry wiki](https://github.com/pry/pry/wiki).
+
+Below are a few features definitely worth checking out, also run
+`help` in a pry session to see what else you can do.
+
+### State navigation
+
+With the [state navigation](https://github.com/pry/pry/wiki/State-navigation)
+you can move around in the code to discover methods and such:
+
+```ruby
+# Change context
+[1] pry(main)> cd Pry
+[2] pry(Pry):1>
+
+# Print methods
+[2] pry(Pry):1> ls -m
+
+# Find a method
+[3] pry(Pry):1> find-method to_yaml
+```
+
+### Source browsing
+
+You [look at the source code](https://github.com/pry/pry/wiki/Source-browsing)
+from your `pry` session:
+
+```ruby
+[1] pry(main)> $ Array#first
+# The above is equivalent to
+[2] pry(main)> cd Array
+[3] pry(Array):1> show-source first
+```
+
+`$` is an alias for `show-source`.
+
+### Documentation browsing
+
+Similar to source browsing, is [Documentation browsing](https://github.com/pry/pry/wiki/Documentation-browsing).
+
+```ruby
+[1] pry(main)> show-doc Array#first
+```
+
+`?` is an alias for `show-doc`.
+
+### Command history
+
+With <kdb>Ctrl+R</kbd> you can search your [command history](https://github.com/pry/pry/wiki/History).
+
+## Stepping
+
+To step through the code, you can use the following commands:
+
+- `break`: Manage breakpoints.
+- `step`: Step execution into the next line or method. Takes an
+  optional numeric argument to step multiple times.
+- `next`: Step over to the next line within the same frame. Also takes
+  an optional numeric argument to step multiple lines.
+- `finish`: Execute until current stack frame returns.
+- `continue`: Continue program execution and end the Pry session.
+
+## Callstack navigation
+
+You also can move around in the callstack with these commands:
+
+- `backtrace`: Shows the current stack. You can use the numbers on the
+  left side with the frame command to navigate the stack.
+- `up`: Moves the stack frame up. Takes an optional numeric argument
+  to move multiple frames.
+- `down`: Moves the stack frame down. Takes an optional numeric
+  argument to move multiple frames.
+- `frame <n>`: Moves to a specific frame. Called without arguments
+  will show the current frame.
+
+## Short commands
+
+When you use `binding.pry` instead of `byebug`, the short commands
+like `s`, `n`, `f`, and `c` do not work.  To reinstall them, add this
+to `~/.pryrc`:
+
+```ruby
+if defined?(PryByebug)
+  Pry.commands.alias_command 's', 'step'
+  Pry.commands.alias_command 'n', 'next'
+  Pry.commands.alias_command 'f', 'finish'
+  Pry.commands.alias_command 'c', 'continue'
+end
+```
+
+## Repeat last command
+
+You can repeat the last command by just hitting the <kbd>Enter</kbd>
+key (e.g., with `step` or`next`), if you place the following snippet
+in your `~/.pryrc`:
+
+```ruby
+Pry::Commands.command /^$/, "repeat last command" do
+  _pry_.run_command Pry.history.to_a.last
+end
+```
+
+`byebug` supports this out-of-the-box.
diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md
index 1a926a660f1..acbfa1850b4 100644
--- a/doc/development/testing_guide/best_practices.md
+++ b/doc/development/testing_guide/best_practices.md
@@ -101,7 +101,7 @@ CHROME_HEADLESS=0 bundle exec rspec some_spec.rb
 
 The test will go by quickly, but this will give you an idea of what's happening.
 
-You can also add `byebug` or `binding.pry` to pause execution and step through
+You can also add `byebug` or `binding.pry` to pause execution and [step through](../pry_debugging.md#stepping)
 the test.
 
 #### Screenshots