Merge pull request #190 from microsoft/octogonz/rushstack-legacy

Rewrite some references to outdated Gulp tooling

websites/rushjs.io/docs/pages/contributing.md

@@ -76,7 +76,7 @@ After saving this file, in VS Code click _"View" --> "Run"_ and choose your "Deb
 
 ## 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.
+Rush builds using the [Heft](https://heft.rushstack.io/) toolchain. You can invoke the `heft` command-line directly for better additional options.
 
 ```bash
 # Full incremental build of Rush and its dependencies, including unit tests

websites/rushjs.io/docs/pages/help/faq.md

@@ -19,7 +19,7 @@ You might be thinking: "Hmmm.. if my current install takes 3 minutes, and you wa
 Nope! Rush works within the existing systems and standards. It just does things better and faster.
 
 - Each project folder remains self-contained (no blurring of package boundaries)
-- It's still possible to build any project without Rush; just do `npm install` and `gulp` as usual
+- It's still possible to build any project without Rush; just do `pnpm install` and `npm run build` as usual (although `workspace:*` [references](https://pnpm.io/workspaces#workspace-protocol-workspace) in **package.json** might need to be removed)
 - A project can be moved to a separate repo at any time, without any code changes; no commitment!
 
 ### Is "Rush Stack" the same thing as Rush?
@@ -46,7 +46,7 @@ Rush Multi-Package Build Tool 2.5.0 - http://aka.ms/rush
 
 NPM seems to say that it is installing version 3.0.1, but when we execute the command, it shows Rush version 2.5.0. What's going on here?!
 
-The problem is that when you type commands like "gulp" or "rush", they are found in your system PATH, which can be pointing to folders from previous installs of NodeJS or NPM.
+The problem is that when you type commands like "heft" or "rush", they are found in your system PATH, which can be pointing to folders from previous installs of NodeJS or NPM.
 
 The fix:
 

websites/rushjs.io/docs/pages/intro/welcome.md

@@ -12,7 +12,7 @@ title: Welcome to Rush!
 
 - **Automatic local linking:** Inside a Rush repo, all your projects are automatically symlinked to each other. When you make a change, you can see the downstream effects without publishing anything, and without any `npm link` headaches. If you don't want certain projects to get linked, that's supported, too.
 
-- **Fast builds:** Rush detects your dependency graph and builds your projects in the right order. If two packages don't directly depend on each other, Rush parallelizes their build as separate NodeJS processes (and shows live console output in a [readable order](https://www.npmjs.com/package/@rushstack/stream-collator)). In practice this multi-process approach can yield more significant speedups than all those async functions in your single-threaded Gulpfile.
+- **Fast builds:** Rush detects your dependency graph and builds your projects in the right order. If two packages don't directly depend on each other, Rush parallelizes their build as separate NodeJS processes (and shows live console output in a [readable order](https://www.npmjs.com/package/@rushstack/stream-collator)). In practice this multi-process approach can yield more significant speedups than all those async functions in your single-process toolchain.
 
 - **Subset and incremental builds:** If you only plan to work with a few projects from your repo, `rush rebuild --to <project>` does a clean build of just your upstream dependencies. After you make changes, `rush rebuild --from <project>` does a clean build of only the affected downstream projects. And if your toolchain is [package-deps-hash](https://www.npmjs.com/package/@rushstack/package-deps-hash) enabled, `rush build` delivers a powerful cross-project incremental build (that also supports subset builds).
 

websites/rushjs.io/docs/pages/intro/why_mono.md

@@ -31,4 +31,4 @@ The emergent principle becomes **"one Git repo per team"**, or even better **"as
 
 [Lots](https://danluu.com/monorepo/) [of](https://medium.com/@bebraw/the-case-for-monorepos-907c1361708a) [people](http://blog.shippable.com/our-journey-to-microservices-and-a-mono-repository) who build large scale business software seem to end up with all their code in one big "monorepo". JavaScript is just the last guy to join the party.
 
-The big concern with this strategy is obviously _**build times**_. JavaScript tools are slower than compiled languages. If one project takes 1 minute to build, and you have 75 projects, in theory you could be looking at a ridiculous 75 minute build time. It seems intimidating, but with an industrial strength toolchain you can scale very far before build times become an issue. Most of our roadmap for Rush and **gulp-core-build** is focused on build times, and we're optimistic that there's still plenty of room for optimizations. With subset/incremental builds, you can in theory avoid rebuilding everything unless a change really does affect everything -- and for that kind of change, it's hard to argue that finding breaks early isn't worth the price of waiting for a longer build.
+The big concern with this strategy is obviously _**build times**_. JavaScript tools are slower than compiled languages. If one project takes 1 minute to build, and you have 75 projects, in theory you could be looking at a ridiculous 75 minute build time. It seems intimidating, but with an industrial strength toolchain you can scale very far before build times become an issue. Most of our roadmap for Rush and Heft is focused on build times, and we're optimistic that there's still plenty of room for optimizations. With subset/incremental builds, you can in theory avoid rebuilding everything unless a change really does affect everything -- and for that kind of change, it's hard to argue that finding breaks early isn't worth the price of waiting for a longer build.

websites/rushjs.io/docs/pages/maintainer/add_to_repo.md

@@ -120,11 +120,11 @@ In order to build your projects, Rush will look for a `"build"` script in the `"
 
 There are a few things to keep in mind when creating a `"build"` script:
 
-- Rush will normally use your system PATH environment variable to find the script commands. However, if you specify a single-word command like "gulp" or "make", Rush will first look for the program in the `common\temp\node_modules\.bin` folder.
+- Rush will normally use your system PATH environment variable to find the script commands. However, if you specify a single-word command like "heft" or "make", Rush will first look for the program in the `common\temp\node_modules\.bin` folder.
 
 - If the process returns a non-zero exit status, Rush will assume there was a failure and will block downstream builds.
 
-- If the command writes anything to the `stderr` stream, Rush will interpret this to mean that at least one error or warning was reported. This will break the build. (This is by design -- if you allow people to merge PRs that "cry wolf", pretty soon you will find that so many warnings have accumulated that nobody even reads them any more.) Some tooling libraries (e.g. Jest) write to `stderr` as part of their normal operation; you will need to [redirect their output](https://github.com/microsoft/rushstack-legacy/blob/main/core-build/gulp-core-build/src/tasks/JestReporter.ts#L14).
+- If the command writes anything to the `stderr` stream, Rush will interpret this to mean that at least one error or warning was reported. This will break the build. (This is by design -- if you allow people to merge PRs that "cry wolf", pretty soon you will find that so many warnings have accumulated that nobody even reads them any more.) Some tooling libraries (e.g. Jest) write to `stderr` as part of their normal operation; you will need to [redirect their output](https://github.com/microsoft/spfx-gulp-tools/blob/main/core-build/gulp-core-build/src/tasks/JestReporter.ts#L23).
 
 - If certain projects don't need to be processed by `rush build`, you still need a `build` entry. Set the value to an empty string (`""`) and Rush will ignore it.
 

websites/rushjs.io/docs/pages/maintainer/custom_commands.md

@@ -173,7 +173,7 @@ How to implement a custom command/parameter? For global commands, Rush simply in
   "typings": "lib/index.d.ts",
   "scripts": {
     "import-strings": "./node_modules/.bin/loc-importer",
-    "build": "./node_modules/.bin/gulp"
+    "build": "./node_modules/.bin/heft build"
   }
 }
 ```

websites/rushjs.io/docs/pages/maintainer/setup_policies.md

@@ -127,28 +127,28 @@ When you run `rush install`, it will create two files that report your dependenc
 - **~/demo/common/config/rush/browser-approved-packages.json**: Packages approved for usage in a web browser. This is generally the stricter of the two types, so by default all new packages are added to this file. For web browser dependencies, the review discussion typically focuses on: _How big is the minified code?_ _What's the license?_ _Are there security issues?_
 - **~/demo/common/config/rush/nonbrowser-approved-packages.json**: Packages approved for usage everywhere _except_ in a web browser. This review discussion typically focuses on: _How much clutter will it pull into our node_modules folder?_ _Do we already have an equivalent package?_ _Is there any real code in there, or is it a just a flimsy wrapper for another package?_
 
-After running `rush install`, the **browser-approved-packages.json** file will look like this.
+After running `rush install`, the **browser-approved-packages.json** file might look like this:
 
 ```javascript
 {
   "packages": [
     {
-      "name": "@microsoft/gulp-core-build",
+      "name": "@rushstack/heft",
       "allowedCategories": [ "internal" ]
     },
     {
-      "name": "@microsoft/node-library-build",
+      "name": "@rushstack/node-library-build",
       "allowedCategories": [ "internal", "published" ]
     },
     {
-      "name": "gulp",
+      "name": "semver",
       "allowedCategories": [ "internal", "published" ]
     }
   ]
 }
 ```
 
-For example, this file is showing that the external dependency **@microsoft/gulp-core-build** was found in the package.json file for an "internal" project (let's say **~/demo/lib1**) but not any "public" project (such as **~/demo/application**).
+For example, this file is showing that the external dependency **@rushstack/heft** was found in the package.json file for an "internal" project (let's say **~/demo/lib1**) but not any "public" project (such as **~/demo/application**).
 
 Rush has no way to detect whether an NPM package is for the browser or not. Since these are all non-browser files, you must manually move them to the other file **browser-approved-packages.json**.
 

websites/rushstack.io/docs/pages/contributing/get_started.md

@@ -11,11 +11,12 @@ We also maintain a number of supporting repositories for documentation and code
 <!-- prettier-ignore-start -->
 | GitHub repo | Contents |
 |-------------|----------|
+| [microsoft/rushstack](https://github.com/microsoft/rushstack) | The main monorepo |
 | [microsoft/rushstack-websites](https://github.com/microsoft/rushstack-websites) | Docusaurus websites for `rushjs.io`, `rushstack.io`, `heft.rushstack.io`, `lfx.rushstack.io`, `api.rushstack.io`, `api-extractor.com`, and `tsdoc.org` |
 | [microsoft/rush-example](https://github.com/microsoft/rush-example) | A barebones example repository for testing Rush commands |
 | [microsoft/rushstack-samples](https://github.com/microsoft/rushstack-samples) | A collection of code samples using the Rush Stack tooling |
-| [microsoft/rushstack-legacy](https://github.com/microsoft/rushstack-legacy) | Legacy projects that are no longer actively developed |
 | [microsoft/tsdoc](https://github.com/microsoft/tsdoc) | TSDoc-related projects are developed in this standalone monorepo |
+| [microsoft/lockfile-explorer-demos](https://github.com/microsoft/lockfile-explorer-demos) | Demo branches for the [Lockfile Explorer](https://lfx.rushstack.io) tutorials |
 <!-- prettier-ignore-end -->
 
 ## Setting up your machine