Contributing

Rush is developed in the monorepo for the Rush Stack family of projects:

     https://github.com/microsoft/rushstack

Contribute to the documentation website in the rushstack-websites GitHub repo.

For general instructions for building Rush and guidelines for submitting PRs, please read the Contributing documentation for the Rush Stack monorepo.

The relevant monorepo project folders are:

• apps/rush - the command line interface front end
• libraries/rush-lib - the automation API and "engine" where all the logic is implemented

Testing Rush builds

Once you have coded your fix and built your branch (as described in the general Contributing 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:

cd rushstack/libraries/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:

# Substitute the full path to your own build of rush-lib:
alias testrush="node ~/git/rushstack/libraries/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/libraries/rush-lib/.vscode/launch.json

{
  // 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

      // The Node.js debugger injects its own messages into the subprocess STDERR, which Rush
      // may misinterpret as a build failure.  You can uncomment this line as a workaround:
      // "env": { "RUSH_ALLOW_WARNINGS_IN_SUCCESSFUL_BUILD": "1" }
    }
  ]
}

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.

TIP: If Rush builds seem to fail in the debugger due to "warnings" such as

Debugger attached.
Waiting for the debugger to disconnect...

...see the code commented above regarding RUSH_ALLOW_WARNINGS_IN_SUCCESSFUL_BUILD.

Building without unit tests

Rush builds using the Heft toolchain. You can invoke the heft command-line directly for better additional options.

# 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
cd rushstack/libraries/rush-lib

rushx build