From df5a62b02f7e935f6dcbcc010a0fcbf9014e57e7 Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Fri, 3 Jul 2020 22:29:29 -0700
Subject: [PATCH] Document how to debug Rush

---
 pages/contributing.md | 66 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/pages/contributing.md b/pages/contributing.md
index 7342f5fa..16b54cdc 100644
--- a/pages/contributing.md
+++ b/pages/contributing.md
@@ -11,3 +11,69 @@ Contribute to the documentation website in the [rushjs.io-website](https://githu
 For general instructions on building Rush and guidelines for submitting PRs, please read the
 [Contributing](https://rushstack.io/pages/contributing/get_started/) documentation for the Rush Stack
 monorepo.
+
+## Testing Rush builds
+
+Once you have coded your fix and built your branch (as described in the general [Contributing](https://rushstack.io/pages/contributing/get_started/) notes), you will want to test your development build of Rush.
+
+Rush features a mechanism called the **version selector**, which reads `rushVersion` from **rush.json** and then automatically installs and invokes that specific version of the engine.  Thus if we launch your build of `@microsoft/rush`, it will not actually run your modified code.  To bypass the version selector, we need to invoke the `@microsoft/rush-lib` engine directly:
+
+```shell
+$ cd rushstack/apps/rush-lib
+$ node ./lib/start.js --help
+```
+
+If you want to make it easy invoke your test build from other locations, we recommend to create a `testrush` command.
+
+For Bash on Mac OS or Linux:
+```shell
+# Substitute the full path to your own build of rush-lib:
+alias testrush="node ~/git/rushstack/apps/rush-lib/lib/start.js"
+```
+
+For Windows, we might create `testrush.cmd` and add it to our system `PATH`:
+```
+@ECHO OFF
+REM Substitute the full path to your own build of rush-lib:
+node "C:\Git\rushstack\apps\rush-lib\lib\start.js" %*
+```
+
+## Debugging Rush
+
+The same approach is used to debug Rush using the VS Code debugger.  Create a debugger configuration file like this:
+
+**rushstack/apps/rush-lib/.vscode/launch.json**
+```js
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug Rush",
+      "program": "${workspaceFolder}/lib/start.js",
+      "args": [ "list", "--json" ],  // <====== specify your Rush command line arguments here
+      "cwd": "(repo folder that you want to debug)"  // <===== specify your target working folder here
+    }
+  ]
+}
+```
+
+After saving this file, in VS Code click *"View" --> "Run"* and choose your "Debug Rush" configuration from the list. Then click *"Run" --> "Start Debugging"* to start debugging. Breakpoints and TypeScript source maps should work correctly.
+
+## Building without unit tests
+
+Rush currently builds using the **gulp-core-build** toolchain which by default runs unit tests, which take a long time.  You can bypass them by invoking gulp directly.
+
+```shell
+# Full incremental build of Rush and its dependencies, including unit tests
+$ rush build --to rush-lib --verbose
+
+# Do a quick build of "rush-lib" only without unit tests
+$ npm install -g gulp
+$ cd rushstack/apps/rush-lib
+$ gulp build
+```