docs: update contributing docs

Author: Chris Anderson

CONTRIBUTING.md

@@ -1,58 +1,40 @@
-# Contribution guide
+# 👩‍💻 Contribution guide
 
+## 🛠 Required tools
 
-## Build the project
-    1. Clone the repo by running 'git clone https://github.com/microsoft/botframework-cli.git'
-    2. Inside the project folder run 'npm install'
-    3. Run 'npm run build'
+We use [rush](https://rushjs.io/) with [pnpm](https://pnpm.js.org) to manage our monorepo. All your commands to build and test will use `rush`/`rushx`.
 
-## Steps to create a new plugin
+ - git
+ - node 10 LTS or 12 LTS 
+   - (other versions not officially supported) (recommend [nvs](https://github.com/jasongin/nvs/releases) to help manage node versions)
+ - rush@5.13.x+
+   - (rush newer rush versions will manage this for you)
+ - (optional) pnpm@5+
+   -  useful to make vs code happy when trying to resolve your typescript version
+ - MacOSX, Windows, "modern" Linux
+   - We develop on Mac and Windows machines, and test on Ubuntu 14+.
 
-    1. Build the project
-    2. Inside the packages folder(https://github.com/microsoft/botframework-cli/tree/master/packages) run 'npx oclif plugin <plugin-name>'
-    3. Follow the wizard and set the prompts:
-    
-      ? npm package: @microsoft/bf-<plugin-name>
-      ? description: <Plugin brief description>
-      ? author: Microsoft
-      ? version: 1.0.0
-      ? license: MIT
-      ? Who is the GitHub owner of repository (https://github.com/OWNER/repo): microsoft
-      ? What is the GitHub name of repository (https://github.com/owner/REPO): botframework-cli
-      ? Select a package manager: npm
-      ? TypeScript: Y
-      ? Use tslint (linter for TypeScript): Y
-      ? Use mocha (testing framework): Y
-      ? Add CI service config (Press <space> to select, <a> to toggle all, <i> to invert selection): select any
-    
-    4. Go to the folder created by the previous command and add @microsoft/bf-cli-command as a dependency in your package.json file
-    
-      "dependencies": {
-        ...,
-        "@microsoft/bf-cli-command": "1.0.0",
-        ...
-      }   
-    
-    5. At the root level(https://github.com/microsoft/botframework-cli) run 'npm run build' to bootstrap the packages
+## ⚡ Quickstart to contribute
 
-## Steps to create a new command
-    1. Inside the plugin folder run 'npx oclif command <command-name>'. 
-    	a. To add a subcommand use a colon separated format as follows: 
-    		<command-name:subcommand-name>
-    2. Replace the import 'import {Command, flags} from '@oclif/command' line inside the newly created command with '@microsoft/bf-cli-command'
-    
-      - import {Command, flags} from '@oclif/command'
-      + import {Command, flags} from '@microsoft/bf-cli-command'
-    
-    3. Add the typing to the flags property like this if needed:
-    
-      static flags: flags.Input<any> = {
-        help: flags.help({description: 'Display help'}),
-      }
-    
-    4. Implement the run method
+0. Fork the repo at https://github.com/microsoft/botframework-cli
+0. Clone your fork - `git clone https://github.com/<YOU>/botframework-cli.git`
+0. `npm i -g @microsoft/rush`
+   - Install rush
+0. `rush update` 
+   - installs and links packages - use `rush install` and `rush link` for readonly
+0. `rush build` 
+   - builds all the projects
+0. `rush test` 
+   - runs tests in all the projects
 
-## General Guidelines
+## 💅 Tips
+
+- DO NOT USE `npm install` (and in general avoid `npm` commands). If you need to add a package, look at `rush add` or modify the package.json directly.
+- We don't hoist common dev dependencies from a single list. It must be declared in each package, but pnpm will only install it once.
+- You can use `rush --help` to get more details about what commands you can run.
+- You can also use `rushx` to run specific commands in a given package (but rush install/link usually needs to have run for it to work).
+
+## 📃 General Guidelines
 
 ### Common Options Rules
 
@@ -79,8 +61,6 @@
 - Detect --in / --out file or folder based on specified value. If need to disambiguate introduce param (only if no way to infer).
 - Use the input/output stream tables below to guide command line I/O processing
 
-
-
 #### Input Stream
 
 | Specified | Expected | Exist  | File Action | Folder Action |
@@ -179,3 +159,58 @@ CLI contribution Software Development Lifecycle is as follows:
 3. Implement. All code must be test-covered at > 90% coverage integrated into CI. 
 4. Schedule a team show & tell demo for introduction, feedback and fine tuning
 
+## ❓ FAQ
+
+### Why rush/pnpm?
+
+Rush and pnpm are newer tools and not all that popular outside of Microsoft, why use them? 
+
+- Speed. We get ordered and parallel builds for free.
+- Standarization. Many of the Microsoft JS repos are moving to `rush`.
+- Quality of life. The command line help, enforcement & customization tools, etc. that come from `rush` and `pnpm` are super useful. Also, we like avoiding the "parent" project for hoisting dependencies. That frequently bites us with our old system.
+
+### Steps to create a new plugin
+
+    1. Build the project
+    2. Inside the packages folder(https://github.com/microsoft/botframework-cli/tree/master/packages) run 'npx oclif plugin <plugin-name>'
+    3. Follow the wizard and set the prompts:
+    
+      ? npm package: @microsoft/bf-<plugin-name>
+      ? description: <Plugin brief description>
+      ? author: Microsoft
+      ? version: 1.0.0
+      ? license: MIT
+      ? Who is the GitHub owner of repository (https://github.com/OWNER/repo): microsoft
+      ? What is the GitHub name of repository (https://github.com/owner/REPO): botframework-cli
+      ? Select a package manager: npm
+      ? TypeScript: Y
+      ? Use tslint (linter for TypeScript): Y
+      ? Use mocha (testing framework): Y
+      ? Add CI service config (Press <space> to select, <a> to toggle all, <i> to invert selection): select any
+    
+    4. Go to the folder created by the previous command and add @microsoft/bf-cli-command as a dependency in your package.json file
+    
+      "dependencies": {
+        ...,
+        "@microsoft/bf-cli-command": "1.0.0",
+        ...
+      }   
+    
+    5. At the root level(https://github.com/microsoft/botframework-cli) run 'npm run build' to bootstrap the packages
+
+### Steps to create a new command
+    1. Inside the plugin folder run 'npx oclif command <command-name>'. 
+    	a. To add a subcommand use a colon separated format as follows: 
+    		<command-name:subcommand-name>
+    2. Replace the import 'import {Command, flags} from '@oclif/command' line inside the newly created command with '@microsoft/bf-cli-command'
+    
+      - import {Command, flags} from '@oclif/command'
+      + import {Command, flags} from '@microsoft/bf-cli-command'
+    
+    3. Add the typing to the flags property like this if needed:
+    
+      static flags: flags.Input<any> = {
+        help: flags.help({description: 'Display help'}),
+      }
+    
+    4. Implement the run method