Re-write getting started docs

1. add getting started 2. add first activity 3. consolidate contributing 4. consolidate readme
firefox-devtools · Nov 28, 2016 · 6a3b393 · 6a3b393
1 parent 3cac635
commit 6a3b393
Show file tree

Hide file tree

Showing 8 changed files with 489 additions and 307 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/README.md b/README.md
@@ -10,66 +10,23 @@ debugger.html is a hackable debugger for modern times, built from the ground up
 [![npm version](https://img.shields.io/npm/v/debugger.html.svg)](https://www.npmjs.com/package/debugger.html)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
 
-## Getting Started
 
-Here are instructions to get the debugger.html application installed and running.
+**Here are the [Getting Started][getting-started] instructions.**
 
-### Linux or MacOs
+### Getting Involved
 
-* `npm i -g [email protected]` - Install Yarn
-* `git clone [email protected]:devtools-html/debugger.html.git` - Clone Debugger
-* `yarn install` - Install dependencies
-* `yarn start` - Start development web server
-
-NOTE: :cat2: We use [Yarn](https://yarnpkg.com) so that we all have the same setup.
-
-### Windows
-
-It is recommended to use Git Shell which comes with [GitHub Desktop] application to emulate bash on Windows.
-
-* `npm i -g [email protected]` - Install Yarn
-* `git clone [email protected]:devtools-html/debugger.html.git` - Clone Debugger
-* `yarn install` - Install dependencies
-* `yarn start` - Start development web server
-
-NOTE: :cat2: We use [Yarn](https://yarnpkg.com) so that we all have the same setup.
-
-### Open the Debugger
-
-After `yarn start`, the debugger will be running on [http://localhost:8000](http://localhost:8000) and you can open it in any browser. [screenshot](https://cloud.githubusercontent.com/assets/254562/20393011/44ca6a8a-aca8-11e6-99f7-05f21767ae6d.png)
-
-Now you have the debugger.html web app running, follow the instructions shown on that page to start up a debug target like a web browser or node.js.
-
-Please read [Getting Started][getting-started] in our [CONTRIBUTING][contributing] document for more detailed instructions.
-
-## Getting Involved
-
-This is an open source project and we would love your help. We have prepared a [CONTRIBUTING][contributing] guide to help you get started, here are some quick links to common questions.
-
-  * [Reporting Bugs][reporting-bugs]
-  * [Suggesting Enhancements][suggesting-enhancements]
-  * [Your First Code Contribution][your-first-code-contribution]
-  * [Pull Requests][pull-requests]
-  * [Writing Code][writing-code]
-    * [Hot Reloading][hot-reloading]
-    * [Tests][tests]
-      * [Unit Tests][unit-tests]
-      * [Integration Tests][integration-tests]
-      * [Linting][linting]
-
-We use the [up for grabs](https://github.com/devtools-html/debugger.html/labels/up%20for%20grabs) label to indicate this work is open for anyone to take.  If you already know what you're doing and want to dive in, take a look at those issues.
+This is an open source project and we would love your help. We have prepared a [CONTRIBUTING][contributing] guide to help you get started.
 
 We strive for collaboration with [mutual respect for each other](./CODE_OF_CONDUCT.md).   Mozilla also has a set of [participation guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/) which goes into greater detail specific to Mozilla employees and contributors.
 
-## Discussion
+### Discussion
 
 We're all on Mozilla's IRC in the [#devtools-html][irc-devtools-html] channel on irc.mozilla.org.
 
-
 * **Open Office Hours** Every Tuesday, Thursday at 3pm EST. [Event](https://calendar.google.com/calendar/render#eventpage_6%7Ceid-MzBtZHBhNm5jcW44dXR0dm1yajliOWQzamNfMjAxNjExMjJUMjAwMDAwWiBodWtoZG9rbzNuMm5oNzZiZGw2dWUya2pqb0Bn-1-0-)
 * **DevTools Call** Every Tuesday at 12pm EST. [info](https://wiki.mozilla.org/DevTools)
 
-## License
+### License
 
 [MPL 2](./LICENSE)
 
@@ -79,14 +36,7 @@ We're all on Mozilla's IRC in the [#devtools-html][irc-devtools-html] channel on
 [mozilla-firefox]:https://www.mozilla.org/firefox/
 
 [contributing]:./CONTRIBUTING.md
-[getting-started]:./CONTRIBUTING.md#getting-started
-
-[getting-started-firefox]:./CONTRIBUTING.md#firefox
-
-[getting-started-chrome]:./CONTRIBUTING.md#chrome
-
-[getting-started-node]:./CONTRIBUTING.md#nodejs
-
+[getting-started]:./docs/local-development.md
 [create-local-config]:./CONTRIBUTING.md#create-a-local-config-file
 
 [reporting-bugs]:./CONTRIBUTING.md#reporting-bugs-bug

diff --git a/bin/chrome-driver.js b/bin/chrome-driver.js
@@ -0,0 +1,22 @@
+const spawn = require('child_process').spawn;
+
+const chromeBinary = "/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome"
+
+const chrome = spawn(chromeBinary, [
+  "--remote-debugging-port=9222",
+  "--no-first-run",
+  "--user-data-dir=/tmp/chrome-dev-profile"
+])
+
+chrome.stdout.on('data', data => console.log(`stdout: ${data}`));
+chrome.stderr.on('data', data => console.log(`stderr: ${data}`));
+chrome.on('close', code => console.log(`chrome exited with code ${code}`));
+chrome.on('error', error => {
+  if (error.code == "ENOENT") {
+    console.log(`Hmm, could not find the path ${chromeBinary}.`)
+    console.log(`Try looking for chrome with ls /Applications`)
+    return;
+  }
+
+  console.log(error)
+});
diff --git a/configs/local.sample.json b/configs/local.sample.json
@@ -1,6 +1,6 @@
 {
   "theme": "light",
-  "hotReloading": true,
+  "hotReloading": false,
   "logging": {
     "actions": false
   },

diff --git a/docs/debugging-the-debugger.md b/docs/debugging-the-debugger.md
@@ -0,0 +1,101 @@
+### Debugging the Debugger
+
+Debugging the Debugger is one of the highest levels of inception. Before you begin, prepare yourself for a mind-bending trip of computer science discovery.
+
+Here are a couple things to keep in mind throughout the journey:
+
+1. When you inspect the running debugger app, you're debugging a web app
+2. The Debugger like other applications has an API to communicate with the browser
+3. There's no magic here. If you can build a web app, you can hack on the debugger!
+4. You are the debugger's principal customer. Remember, the customer is always right!
+
+#### Playing with the debugger
+
+Lets setup up the environment [gif](http://g.recordit.co/WjHZaXKifZ.gif)
+
+1. open firegox and go to a tab you want to debug. I recommend [todomvc](http://todomvc.com/examples/vanillajs/) and
+2. go to [localhost:8000](localhost:8000) in a new tab (or chrome)
+3. click on the tab you want to debug
+3. open the debugger's debugger (cmd-option-i).
+
+Go crazy...
+
+##### Design a retro theme
+
+Lets design a new theme for the debugger, it's not too hard!
+
+Goals:
+- style the tabs
+- style the tree
+- style whatever
+- share what you come up with [here](https://github.com/devtools-html/debugger.html/issues/1247)! We'd love to see it and who knows maybe we can compete over the most stylish theme.
+
+![](https://cloud.githubusercontent.com/assets/254562/20683683/ec030354-b57a-11e6-98bc-c8da75721e78.png)
+
+
+##### Make breakpoints dance
+
+Adding a breakpoint is a critical piece in the inception game...
+Lets make the debugger do something special when a breakpoint is added.
+
+
+```diff
+diff --git a/src/components/Editor.js b/src/components/Editor.js
+index ae71d2d..66e0c04 100644
+--- a/src/components/Editor.js
++++ b/src/components/Editor.js
+@@ -78,11 +78,14 @@ const Editor = React.createClass({
+       return this.closeConditionalPanel(line);
+     }
+
++    // => hamster dance
++
+     this.toggleBreakpoint(line);
+   },
+```
+
+We currently don't have anything awesome as a demo. Please share what you come up with [here](https://github.com/devtools-html/debugger.html/issues/1247) and we can improve the docs!
+
+#### Pausing FTW
+
+When the debugger pauses, the fun begins. Here's a [gif](http://g.recordit.co/qutDioRQvy.gif) of what the debugger does normally when it pauses. You're mission if you choose to accept it, is to make it do something truly weird.
+
+Here's a patch to get you started where we check in the Editor to see if we're paused in a re-render.
+
+```diff
+diff --git a/src/components/Editor.js b/src/components/Editor.js
+index ae71d2d..6690d05 100644
+--- a/src/components/Editor.js
++++ b/src/components/Editor.js
+@@ -78,11 +78,14 @@ const Editor = React.createClass({
+       return this.closeConditionalPanel(line);
+     }
+
+     const line = this.editor.codeMirror.lineAtHeight(event.clientY);
+     const bp = breakpointAtLine(this.props.breakpoints, line);
+     this.showGutterMenu(event, line, bp);
+@@ -329,6 +332,11 @@ const Editor = React.createClass({
+       this.showSourceText(sourceText, selectedLocation);
+     }
+
++    // the debugger is paused
++    if (nextProps.selectedFrame) {
++      // do something really cool here
++    }
+```
+
+#### Next Steps
+
+Now that you've internalized the debugger philosophy, it's time to start putting this wisdom to use.
+
+1. When you inspect the running debugger app, you're debugging a web app
+2. The Debugger like other applications has an API to communicate with the browser
+3. There's no magic here. If you can build a web app, you can hack on the debugger!
+4. You are the debugger's principal customer. Remember, the customer is always right!
+
+
+**Share what you know** Give a talk in school, work, or a local meetup. I'm willing to bet your audience will not know the debugger is a web app!
+
+- here are @amitzur's [slides](https://docs.google.com/presentation/d/1jdnvL-BwwxEuFbb9tiRxcT6UT-Ua0jGhy9FKBT4b43E/edit) from his [talk](https://twitter.com/amitzur/status/790153843946426369)
+
+**Contribute back** take a look at how you can [contribute](../contributing.md#how-can-i-contribute). We would love the help!
diff --git a/docs/getting-setup.md b/docs/getting-setup.md
@@ -0,0 +1,165 @@
+### Getting Setup
+
+##### Overview
+
+The debugger.html is a web application that makes a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) connection to a debuggable target like the JavaScript engine of a web browser.  The web application then interprets data and sends commands to the JS engine to manage the debugging environment; for example by creating a breakpoint or displaying that the JS engine is paused at a breakpoint.
+
+![debugger - web browser](https://cloud.githubusercontent.com/assets/2134/16933811/babb4eec-4d05-11e6-8c7e-f133e54b756f.png)
+
+![](http://g.recordit.co/WjHZaXKifZ.gif)
+
+
+##### Install the Debugger
+
+**Install Yarn**
+
+```bash
+npm i -g [email protected]
+```
+
+Common Questions:
+* *Why Yarn and not NPM?* We use [Yarn](https://yarnpkg.com) :cat2: so that everyone has the same setup.
+* *Why Yarn 0.16.1?* Yarn is a new tool and the latest version currently has some issues.
+
+**Install dependencies**
+
+```bash
+git clone [email protected]:devtools-html/debugger.html.git
+cd debugger.html
+yarn install
+```
+
+Yay! :star2:
+
+NOTE: We're still working out the kinks for Yarn, so if something goes wrong feel free to comment on this [issue](https://github.com/devtools-html/debugger.html/issues/1216).
+
+
+##### Start Debugger Inception
+
+**Open Firefox**
+
+```bash
+yarn run firefox
+```
+
+Open some tabs in firefox you want to debug. I recommend [todomvc](http://todomvc.com/examples/vanillajs/) [screenshot](https://cloud.githubusercontent.com/assets/254562/20439409/55e3994a-ad89-11e6-8e76-55e18c7c0d75.png)
+
+Common Questions:
+* *Why am I opening Firefox from the terminal?* The firefox command opens firefox with special permissions that enable remote debugging.
+
+**Start the Debugger**
+
+Open a new tab in the terminal and run:
+
+```bash
+cd debugger.html
+yarn start
+```
+
+**Start Inception**
+
+Go to `localhost:8000` in any browser to view the Debugger.  
+You should see the open Firefox tabs that you can debug! [screenshot](https://cloud.githubusercontent.com/assets/254562/20439428/7498808a-ad89-11e6-895d-d6db320c5009.png)
+
+**Next Steps**
+
+* Go [here](./debugging-the-debugger.md) if you want to start debugging the debugger!
+
+
+### Appendix
+
+#### Quick Setup
+
+This setup is for people on the DevTools team and DevTools wizards.
+
+```bash
+npm i -g [email protected]
+git clone [email protected]:devtools-html/debugger.html.git
+cd debugger.html
+yarn install
+
+# close firefox if it's already running
+/Applications/Firefox.app/Contents/MacOS/firefox-bin --start-debugger-server 6080 -P development
+
+# create a new terminal tab
+cd debugger.html
+yarn start
+```
+
+#### Starting Firefox
+
+If you're looking for an alternative to `yarn run firefox`, you have two options: cli, gcli.
+
+**Firefox CLI**
+
+1. run `firefox-bin` from the command line
+```bash
+/Applications/Firefox.app/Contents/MacOS/firefox-bin --start-debugger-server 6080 -P development
+```
+
+NOTE: You'll be shown a prompt to create a new "development" profile. The development profile is where your remote development user settings will be kept. *It's a good thing :)*
+
+2. Go to `about:config` and set these configs
+
+Navigate to `about:config` and accept any warning message. Then search for the following preferences and double click them to toggle their values to the following. [example](http://g.recordit.co/3VsHIooZ9q.gif)
+
+* `devtools.debugger.remote-enabled` to `true`
+* `devtools.chrome.enabled` to `true`
+* `devtools.debugger.prompt-connection` to `false`
+
+3. restart Firefox
+
+Close firefox and re-open it with the `firefox-bin` command.
+
+**Firefox GCLI**
+
+* open Firefox
+* *shift-F2* Open GCLI
+* *listen 6080* - start listening on 6080
+
+NOTE: this assumes that you've set the other appropriate `about:configs`
+
+#### Starting Chrome
+
+There are two ways to run chrome. Here's the easy way to run chrome
+
+```bash
+yarn run chrome
+```
+
+Here's the slightly harder way.
+
+```bash
+ /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --no-first-run --user-data-dir=/tmp/chrome-dev-profile
+```
+
+NOTE: that the [script](../bin/chrome-driver) just automates the command :)
+
+#### Starting Node
+
+It's easy to start Node in a mode where DevTools will find it:
+
+* *--inspect* - tells node to open a debugger server
+* *--inspect=9223* - tells node to open a debugger server on 9223 instead of 9229.
+* *--debug-brk* - tells node to pause on the first statement
+
+```bash
+node --inspect --debug-brk ./node_modules/.bin/webpack
+```
+
+NOTE: *./node_modules/.bin/webpack* could be anything. We're often debugging webpack these days so it's often appropriate :/
+
+**Note:** Currently Node.js debugging is limited in some ways, there isn't support for seeing variables or the console, but you can manage breakpoints and navigate code execution (pause, step-in, step-over, etc.) in the debugger across various sources.
+
+#### Windows + Linux setup
+
+Windows and Linux should *just work*, but unfortunately there are several edge cases.
+
+If you find any issues on these two platforms comment on these issues:
+* [windows](https://github.com/devtools-html/debugger.html/issues/1248)
+* [linux](https://github.com/devtools-html/debugger.html/issues/1082)
+
+
+```
+C:\Program Files (x86)\Mozilla Firefox\firefox.exe -start-debugger-server 6080 -P development
+```