Add information from doc/hacking.md and doc/make_cheatsheet.md back i… (#5963)

Add information from doc/hacking.md and doc/make_cheatsheet.md back into contributing docs

4 files changed, 105 insertions, 118 deletions

diff --git a/doc/contributing.md b/doc/contributing.md
index a8deea7969..a6c63de9b2 100644
--- a/doc/contributing.md
+++ b/doc/contributing.md
@@ -9,3 +9,4 @@ This guide outlines ways to get started with contributing to Ruby:
   to change Ruby's documentation, code, test suite, or standard libraries
 * [Making changes to Ruby standard libraries](contributing/making_changes_to_stdlibs.md): How to build, test, and contribute to Ruby standard libraries
 * [Making changes to Ruby documentation](contributing/documentation_guide.md): How to make changes to Ruby documentation
+* [Benchmarking Ruby](https://github.com/ruby/ruby/tree/master/benchmark#make-benchmark): How to benchmark Ruby
diff --git a/doc/contributing/building_ruby.md b/doc/contributing/building_ruby.md
index f20eacc0ae..52d6042ec3 100644
--- a/doc/contributing/building_ruby.md
+++ b/doc/contributing/building_ruby.md
@@ -25,17 +25,27 @@
     git clone https://github.com/ruby/ruby.git
     ```
 
-4. Generate the configuration files and build:
+4. Generate the configuration files and build. It's generally advisable to use a build directory:
 
     ```
     ./autogen.sh
-    mkdir build && cd build # its good practice to build outside of source dir
+    mkdir build && cd build # it's good practice to build outside of source dir
     mkdir ~/.rubies # we will install to .rubies/ruby-master in our home dir
     ../configure --prefix="${HOME}/.rubies/ruby-master"
     make install
     ```
 
-5. [Run tests](testing_ruby.md) to confirm your build succeeded
+5. Optional: If you are frequently building Ruby, disabling documentation will reduce the time it takes to `make`:
+
+    ``` shell
+    ../configure --disable-install-doc
+    ```
+
+6. [Run tests](testing_ruby.md) to confirm your build succeeded
+
+### Unexplainable Build Errors
+
+If you are having unexplainable build errors, after saving all your work, try running `git clean -xfd` in the source root to remove all git ignored local files. If you are working from a source directory that's been updated several times, you may have temporary build artifacts from previous releases which can cause build failures.
 
 ## More details
 
@@ -44,13 +54,31 @@ about Ruby's build to help out.
 
 ### Running make scripts in parallel
 
-To run make scripts in parallel, pass flag `-j<number of processes>`. For instance,
+In GNU make and BSD make implementations, to run a specific make script in parallel, pass the flag `-j<number of processes>`. For instance,
 to run tests on 8 processes, use:
 
 ```
 make test-all -j8
 ```
 
+We can also set `MAKEFLAGS` to run _all_ `make` commands in parallel.
+
+Having the right `--jobs` flag will ensure all processors are utilized when building software projects. To do this effectively, you can set `MAKEFLAGS` in your shell configuration/profile:
+
+``` shell
+# On macOS with Fish shell:
+export MAKEFLAGS="--jobs "(sysctl -n hw.ncpu)
+
+# On macOS with Bash/ZSH shell:
+export MAKEFLAGS="--jobs $(sysctl -n hw.ncpu)"
+
+# On Linux with Fish shell:
+export MAKEFLAGS="--jobs "(nproc)
+
+# On Linux with Bash/ZSH shell:
+export MAKEFLAGS="--jobs $(nproc)"
+```
+
 ### Miniruby vs Ruby
 
 Miniruby is a version of Ruby which has no external dependencies and lacks certain features.
@@ -72,3 +100,41 @@ with the Ruby script you'd like to run. You can use the following make targets:
 * `make runruby`: Runs `test.rb` using Ruby
 * `make lldb-ruby`: Runs `test.rb` using Ruby in lldb
 * `make gdb-ruby`: Runs `test.rb` using Ruby in gdb
+
+### Building with Address Sanitizer
+
+Using the address sanitizer is a great way to detect memory issues.
+
+``` shell
+./autogen.sh
+mkdir build && cd build
+export ASAN_OPTIONS="halt_on_error=0:use_sigaltstack=0:detect_leaks=0"
+../configure cppflags="-fsanitize=address -fno-omit-frame-pointer" optflags=-O0 LDFLAGS="-fsanitize=address -fno-omit-frame-pointer"
+make
+```
+
+On Linux it is important to specify `-O0` when debugging. This is especially true for ASAN which sometimes works incorrectly at higher optimisation levels.
+
+## How to measure coverage of C and Ruby code
+
+You need to be able to use gcc (gcov) and lcov visualizer.
+
+```
+./autogen.sh
+./configure --enable-gcov
+make
+make update-coverage
+rm -f test-coverage.dat
+make test-all COVERAGE=true
+make lcov
+open lcov-out/index.html
+```
+
+If you need only C code coverage, you can remove `COVERAGE=true` from the above process.
+You can also use `gcov` command directly to get per-file coverage.
+
+If you need only Ruby code coverage, you can remove `--enable-gcov`.
+Note that `test-coverage.dat` accumulates all runs of `make test-all`.
+Make sure that you remove the file if you want to measure one test run.
+
+You can see the coverage result of CI: https://rubyci.org/coverage
diff --git a/doc/contributing/testing_ruby.md b/doc/contributing/testing_ruby.md
index c54b14c710..74300d221d 100644
--- a/doc/contributing/testing_ruby.md
+++ b/doc/contributing/testing_ruby.md
@@ -32,6 +32,13 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
     make test OPTS=-v
     ```
 
+    To run a file or directory with GNU make, we can use:
+
+    ```
+    make test/ruby/test_foo.rb
+    make test/ruby/test_foo.rb TESTOPTS="-n /test_bar/"
+    ```
+
 2. [test/](https://github.com/ruby/ruby/tree/master/test)
 
     This is a more comprehensive test suite that runs on Ruby. We can run it with:
@@ -40,13 +47,19 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
     make test-all
     ```
 
-    We can run a specific test file in this suite using the `TESTS` environment variable, for example:
+    We can run a specific test directory in this suite using the `TESTS` option, for example:
+
+    ```
+    make test-all TESTS=test/rubygems
+    ```
+
+    We can run a specific test file in this suite by also using the `TESTS` option, for example:
 
     ```
     make test-all TESTS=test/ruby/test_array.rb
     ```
 
-    We can run a specific test in this suite using the `TESTS` environment variable, specifying
+    We can run a specific test in this suite using the `TESTS` option, specifying
     first the file name, and then the test name, prefixed with `--name`. For example:
 
     ```
@@ -73,7 +86,13 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
     make test-spec
     ```
 
-    To run a specific file, we can use `MSPECOPT` to specify the file:
+    To run a specific directory, we can use `MSPECOPT` to specify the directory:
+
+    ```
+    make test-spec MSPECOPT=spec/ruby/core/array
+    ```
+
+    To run a specific file, we can also use `MSPECOPT` to specify the file:
 
     ```
     make test-spec MSPECOPT=spec/ruby/core/array/any_spec.rb
@@ -91,6 +110,12 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
     make test-spec MSPECOPT=-Vfs
     ```
 
+    To run a ruby-spec file or directory with GNU make, we can use
+
+    ```
+    make spec/ruby/core/foo/bar_spec.rb
+    ```
+
 4. [spec/bundler](https://github.com/ruby/ruby/tree/master/spec/bundler)
 
     The bundler test suite exists in [the RubyGems repository](https://github.com/rubygems/rubygems/tree/master/bundler/spec) and is mirrored into the `spec/bundler` directory in the Ruby repository. We can run this using:
@@ -98,3 +123,9 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
     ```
     make test-bundler
     ```
+
+    To run a specific bundler spec file, we can use `BUNDLER_SPECS` as follows:
+
+    ```
+    $ make test-bundler BUNDLER_SPECS=commands/exec_spec.rb
+    ```
diff --git a/doc/hacking.md b/doc/hacking.md
deleted file mode 100644
index c326e13532..0000000000
--- a/doc/hacking.md
+++ /dev/null
@@ -1,111 +0,0 @@
-# Ruby Hacking Guide
-
-This document gives some helpful instructions which should make your experience as a Ruby core developer easier.
-
-## Setup
-
-### Make
-
-It's common to want to compile things as quickly as possible. Ensuring `make` has the right `--jobs` flag will ensure all processors are utilized when building software projects To do this effectively, you can set `MAKEFLAGS` in your shell configuration/profile:
-
-``` shell
-# On macOS with Fish shell:
-export MAKEFLAGS="--jobs "(sysctl -n hw.ncpu)
-
-# On macOS with Bash/ZSH shell:
-export MAKEFLAGS="--jobs $(sysctl -n hw.ncpu)"
-
-# On Linux with Fish shell:
-export MAKEFLAGS="--jobs "(nproc)
-
-# On Linux with Bash/ZSH shell:
-export MAKEFLAGS="--jobs $(nproc)"
-```
-
-## Configure Ruby
-
-It's generally advisable to use a build directory.
-
-``` shell
-./autogen.sh
-mkdir build
-cd build
-../configure --prefix $HOME/.rubies/ruby-head
-make install
-```
-
-### Without Documentation
-
-If you are frequently building Ruby, this will reduce the time it takes to `make install`.
-
-``` shell
-../configure --disable-install-doc
-```
-
-### Unexplainable Build Errors
-
-If you are having unexplainable build errors, after saving all your work, try running `git clean -xfd` in the source root to remove all git ignored local files. If you are working from a source directory that's been updated several times, you may have temporary build artefacts from previous releases which can cause build failures.
-
-## Running Ruby
-
-### Run Local Test Script
-
-You can create a file in the Ruby source root called `test.rb`. You can build `miniruby` and execute this script:
-
-``` shell
-make run
-```
-
-If you want more of the standard library, you can use `runruby` instead of `run`.
-
-## Running Tests
-
-You can run the following tests at once:
-
-``` shell
-make check
-```
-
-### Run Bootstrap Tests
-
-There are a set of tests in `bootstraptest/` which cover most basic features of the core Ruby language.
-
-``` shell
-make test
-```
-
-### Run Extensive Tests
-
-There are extensive tests in `test/` which cover a wide range of features of the Ruby core language.
-
-``` shell
-make test-all
-```
-
-You can run specific tests by specifying their path:
-
-``` shell
-make test-all TESTS=../test/fiber/test_io.rb
-```
-
-### Run Ruby Spec Suite Tests
-
-The [Ruby Spec Suite](https://github.com/ruby/spec/) is a test suite that aims to provide an executable description for the behaviour of the language.
-
-``` shell
-make test-spec
-```
-
-### Building with Address Sanitizer
-
-Using the address sanitizer is a great way to detect memory issues.
-
-``` shell
-> ./autogen.sh
-> mkdir build && cd build
-> export ASAN_OPTIONS="halt_on_error=0:use_sigaltstack=0:detect_leaks=0"
-> ../configure cppflags="-fsanitize=address -fno-omit-frame-pointer" optflags=-O0 LDFLAGS="-fsanitize=address -fno-omit-frame-pointer"
-> make
-```
-
-On Linux it is important to specify -O0 when debugging and this is especially true for ASAN which sometimes works incorrectly at higher optimisation levels.