diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 77059a936c..cc84b4b254 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,17 +6,7 @@ We respect your time and want to help you make the most of it as you learn more #### Table Of Contents -[What should I know before I get started?](#what-should-i-know-before-i-get-started) - * [debugger.html](#debuggerhtml) - * [devtools.html](#devtoolshtml) - * [Firefox Developer Tools](#firefox-developer-tools) - [Getting Started](#getting-started) - * [Web Application](#web-application) - * [Debuggable Targets](#debuggable-targets) - * [Firefox Remote Debugging](#firefox) - * [Chrome Remote Debugging](#chrome) - * [Node.js Remote Debugging](#nodejs) [How Can I Contribute?](#how-can-i-contribute) * [Reporting Bugs](#reporting-bugs-bug) @@ -35,126 +25,18 @@ We respect your time and want to help you make the most of it as you learn more * [Configuration](#configuration) * [Create a local config file](#create-a-local-config-file) * [Issues and Pull Request labels](#issues-and-pull-requests) + * [Project Overview](#project-overview) + * [debugger.html](#debuggerhtml) + * [devtools.html](#devtoolshtml) + * [Firefox Developer Tools](#firefox-developer-tools) -## What should I know before I get started? +## Getting Started The developer tools in most major browsers are just web applications. They are HTML & JS rendered by the browser and talk to the browser itself through an API that gives access to the page internals. This project is a brand new web application interface for JavaScript debugging designed for browsers and JS environments. 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. -### debugger.html - -The debugger.html project is a JavaScript debugger built from the ground up using modern web application technologies. It is designed first for debugging Firefox but also for working with projects like Chrome and Node. The name debugger.html was chosen because this debugger interface is being written using modern web technologies where as the previous Firefox debugger was written in [XUL](https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XUL). - -### devtools.html - -devtools.html is the larger umbrella initiative that encompasses the debugger.html and several other devtools projects. The devtools.html project claims its origin from a demo for a Mozilla (Dec 2015) work week in Orlando, FL USA where the team worked under a tight deadline to provide a proof of concept of the Firefox developer tools running in pure HTML; even outside of Firefox. The code for that demo can be found on GitHub under [@joewalker/devtools.html](https://github.com/joewalker/devtools.html). - -From that original demo the devtools.html project has progressed quite a bit. To learn more about it please read the [devtools.html proposal document](https://docs.google.com/document/d/1_5aerWTN_GVofr6YQVjmJlaGfZ4nv5YKZmdGHewfTpE/edit#heading=h.dw3amfbdp0lh) and take a look at the [devtools.html meta bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1263750) for tracking progress. - -### Firefox Developer Tools - -The debugger.html project is targeted to land in Firefox for Firefox 52. However if you're looking to work directly on the DevTools project which ships developer tools for Firefox and Firefox Developer Edition right now you can find more information on the Mozilla wiki [DevTools / Get Involved](https://wiki.mozilla.org/DevTools/GetInvolved). - -## Getting Started - -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) - -### Web Application - -First we need to get the web application running. Within the source code directory, from the command line run these commands. - -### Linux or MacOs - -* `npm i -g yarn@0.16.1` - Install Yarn -* `git clone git@github.com: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 yarn@0.16.1` - Install Yarn -* `git clone git@github.com: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) - -### Debuggable Targets - -The following are instructions for getting Firefox, Chrome, and Node running with remote debugging turned on. Remote debugging is necessary for the debugger.html project to connect to these targets. - -#### Firefox - -The following command will automatically start a remote debuggable version of Firefox using a temporary profile and set all the necessary preferences for you. This command runs Firefox in a selenium environment that is great for quick testing. - -``` -$ yarn run firefox -``` - -When firefox is running, reload `localhost:8000` and you'll see the available firefox tabs to debug in the debugger. ![screenshot](https://cloud.githubusercontent.com/assets/254562/20393075/7e494024-aca8-11e6-8578-19a6d73be6ed.png) - -**Command line option** - -Here are the instructions for running Firefox from the command line without selenium: - -**MacOs**: - -``` -$ /Applications/Firefox.app/Contents/MacOS/firefox-bin --start-debugger-server 6080 -P development -``` - -**Windows:** - -``` -C:\Program Files (x86)\Mozilla Firefox\firefox.exe -start-debugger-server 6080 -P development -``` - -> If this command doesn't work for your OS or Firefox version see the other [Firefox commands for running in a debuggable state](./docs/remotely-debuggable-browsers.md#firefox) - -**NOTE**: The Firefox started from the `yarn run` command automatically sets the following necessary flags which you will need to do manually if you ran Firefox from the command line. - -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` - -Once you have Firefox running in a debuggable state go back up to instructions for restarting your development server. - -#### Chrome - -Start by running Chrome from the terminal with remote debugging turned on. - -``` -/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --no-first-run --user-data-dir=/tmp/chrome-dev-profile http://localhost:7999/todomvc/ -``` - -* If this command doesn't work for your OS or Chrome version see the other [Chrome commands for running in a debuggable state](./docs/remotely-debuggable-browsers.md#chrome) -* NOTE: This command also creates a new _temporary_ profile - - -#### Node.js - -Debugging node requires at least node v6.3.0 and running node with the `inspect` flag turned on. Here's what running node looks like when running an example `server.js` file. - -``` -$ node --inspect server.js -``` - -With node running in _inspect mode_ go to your browser running `localhost:8000` and click **[connect to Node](http://localhost:8000/?ws=localhost:9229/node)** - -**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. +[Getting Started](./docs/getting-started.md) ## How Can I Contribute? @@ -193,7 +75,6 @@ There are several difficulty levels, *easy*, *medium*, *hard*. We recommend grab * [difficulty:medium][labels-difficulty-medium] - more complex and may not have as clear expectations. * [difficulty:hard][labels-difficulty-hard] - complex and has some open technical questions. - To begin your work make sure you follow these steps: * [Fork this project](https://github.com/devtools-html/debugger.html#fork-destination-box) @@ -234,124 +115,20 @@ When a person is assigned to an issue this indicates an _intent to implement_. > **Working on your first Pull Request?** You can learn how from this *free* series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github) -#### Hot Reloading :fire: - -Hot Reloading watches for changes in the React Components JS and CSS and propagates those changes up to the application without changing the state of the application. You want this turned on. - -To enabled Hot Reloading: - -* [Create a local config file](#create-a-local-config-file) if you don't already have one -* Edit the `config/local.json` you just created to change the value of `hotReloading` to be `true` - -```json -{ - "hotReloading": true -} -``` - -* Restart your development server by typing `ctrl+c` in the Terminal and run `yarn start` again - -Read more about [Hot Reloading](./docs/local-development.md#hot-reloading) - -### Logging - -Logging information can be very useful when developing, and there are a few logging options available to you. - -To enable logging: - -* [Create a local config file](#create-a-local-config-file) if you don't already have one -* Edit your local config, changing the value of the logger type you want to see to `true` - -```json - "logging": { - "client": false, - "firefoxProxy": false, - "actions": true - } -``` - -Let's cover the logging types. - -* client - This option is currently unused. - -* firefoxProxy - This logger outputs a verbose output of all the Firefox protocol packets to your shell. - -* actions - This logger outputs the Redux actions fired to the browser console. - -### Tests - -Your code must pass all tests to be merged in. Your tests should pass locally before you create a PR and the CI should run an automated test that also passes. - -Here's how can run all the unit tests, lints, and integration tests at once: - -``` -$ yarn run test-all -``` - -#### Unit Tests - -* `yarn test` - Run tests headlessly - * These are the basic unit tests which must always pass -* `yarn run mocha-server` - Run tests in the browser once you open `http://localhost:8003` - * This runs tests in the browser and is useful for fixing errors in the karma tests - -#### Integration tests - -We use [mochitests](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Mochitest) to do integration testing. Running these integration tests locally requires some finesse and so as a contributor we only ask that you run the unit tests. The mochitests will be run by the automated testing which runs once you've made a pull request and the maintainers are happy to help you through any issues which arise from that. - -Learn more about mochitests in our [mochitests docs](./docs/mochitests.md). - -#### Linting - -Run all of lint checks (JS + CSS) run the following command: - -``` -$ yarn run lint -``` - -##### Lint CSS +### Local Development :computer: -We use [Stylelint](http://stylelint.io/) to maintain our CSS styles. The [.stylelintrc](https://github.com/devtools-html/debugger.html/blob/master/.stylelintrc) file contains the style definitions, please adhere to those styles when making changes. +Go to [local Development](./docs/local-development.md) to learn about: -To test your CSS changes run the command: +* [Configs](./docs/local-development.md#configs) +* [Hot Reloading](./docs/local-development.md#hot-reloading) +* [Themes](./docs/local-development.md#themes) +* [Internationalization](./docs/local-development.md#internationalization) +* [Prefs](./docs/local-development.md#prefs) +* [Flow](./docs/local-development.md#flow) +* [Logging](./docs/local-development.md#logging) +* [Testing](./docs/local-development.md#testing) +* [Linting](./docs/local-development.md#linting) -``` -$ yarn run lint-css -``` - -##### Lint JS - -We use [eslint](http://eslint.org/) to maintain our JavaScript styles. The [.eslintrc](https://github.com/devtools-html/debugger.html/blob/master/.eslintrc) file contains our style definitions, please adhere to those styles when making changes. - -To test your JS changes run the command: - -``` -$ yarn run lint-js -``` - -To automatically fix many errors run the command: - -``` -$ yarn run lint-fix -``` - -## Configuration - -All default config values are in [`packages/devtools-config/configs/development.json`](./packages/devtools-config/configs/development.json), to override these values you need to [create a local config file](#create-a-local-config-file). - -Here are the most common development configuration options: - -* `logging` - * `firefoxProxy` Enables logging the Firefox protocol in the terminal running `yarn start` -* `chrome` - * `debug` Enables listening for remotely debuggable Chrome browsers -* `hotReloading` enables [Hot Reloading](./docs/local-development.md#hot-reloading) of CSS and React - -For a list of all the configuration options see the [packages/devtools-config/README.md](./packages/devtools-config/README.md) - -### Create a local config file - -* Copy the [`configs/development.json`](./configs/development.json) to `configs/local.json` ## Issues and Pull Request labels @@ -387,3 +164,19 @@ These are the [labels](https://github.com/devtools-html/debugger.html/labels) we [labels-not-actionable]:https://github.com/devtools-html/debugger.html/labels/not%20actionable [GitHub Desktop]:https://desktop.github.com/ + +## Project Overview + +### debugger.html + +The debugger.html project is a JavaScript debugger built from the ground up using modern web application technologies. It is designed first for debugging Firefox but also for working with projects like Chrome and Node. The name debugger.html was chosen because this debugger interface is being written using modern web technologies where as the previous Firefox debugger was written in [XUL](https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XUL). + +### devtools.html + +devtools.html is the larger umbrella initiative that encompasses the debugger.html and several other devtools projects. The devtools.html project claims its origin from a demo for a Mozilla (Dec 2015) work week in Orlando, FL USA where the team worked under a tight deadline to provide a proof of concept of the Firefox developer tools running in pure HTML; even outside of Firefox. The code for that demo can be found on GitHub under [@joewalker/devtools.html](https://github.com/joewalker/devtools.html). + +From that original demo the devtools.html project has progressed quite a bit. To learn more about it please read the [devtools.html proposal document](https://docs.google.com/document/d/1_5aerWTN_GVofr6YQVjmJlaGfZ4nv5YKZmdGHewfTpE/edit#heading=h.dw3amfbdp0lh) and take a look at the [devtools.html meta bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1263750) for tracking progress. + +### Firefox Developer Tools + +The debugger.html project is targeted to land in Firefox for Firefox 52. However if you're looking to work directly on the DevTools project which ships developer tools for Firefox and Firefox Developer Edition right now you can find more information on the Mozilla wiki [DevTools / Get Involved](https://wiki.mozilla.org/DevTools/GetInvolved). diff --git a/README.md b/README.md index 5b7a7f2cd1..8bac708e71 100644 --- a/README.md +++ b/README.md @@ -10,66 +10,39 @@ 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 +### Getting Setup -Here are instructions to get the debugger.html application installed and running. +Here's the *quick setup*, if you're getting started, I recommend the detailed [getting started][getting-started] instructions. -### Linux or MacOs -* `npm i -g yarn@0.16.1` - Install Yarn -* `git clone git@github.com:devtools-html/debugger.html.git` - Clone Debugger -* `yarn install` - Install dependencies -* `yarn start` - Start development web server +```bash +npm i -g yarn@0.16.1 +git clone git@github.com:devtools-html/debugger.html.git -NOTE: :cat2: We use [Yarn](https://yarnpkg.com) so that we all have the same setup. +cd debugger.html +yarn install +yarn run firefox -### Windows +# create a new terminal tab +cd debugger.html +yarn start +``` -It is recommended to use Git Shell which comes with [GitHub Desktop] application to emulate bash on Windows. -* `npm i -g yarn@0.16.1` - Install Yarn -* `git clone git@github.com:devtools-html/debugger.html.git` - Clone Debugger -* `yarn install` - Install dependencies -* `yarn start` - Start development web server +### Getting Involved -NOTE: :cat2: We use [Yarn](https://yarnpkg.com) so that we all have the same setup. +This is an open source project and we would love your help. We have prepared a [CONTRIBUTING][contributing] guide to help you get started. -### Open the Debugger +We strive for collaboration with [mutual respect for each other][contributing]. 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. -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. - -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) @@ -78,27 +51,8 @@ We're all on Mozilla's IRC in the [#devtools-html][irc-devtools-html] channel on [mozilla]:https://www.mozilla.org/ [mozilla-firefox]:https://www.mozilla.org/firefox/ +[getting-started]:./docs/getting-setup.md [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 - -[create-local-config]:./CONTRIBUTING.md#create-a-local-config-file - -[reporting-bugs]:./CONTRIBUTING.md#reporting-bugs-bug -[suggesting-enhancements]:./CONTRIBUTING.md#suggesting-enhancements-new -[your-first-code-contribution]:./CONTRIBUTING.md#your-first-code-contribution -[pull-requests]:./CONTRIBUTING.md#pull-requests -[writing-code]:./CONTRIBUTING.md#writing-code-computer -[hot-reloading]:./CONTRIBUTING.md#hot-reloading-fire -[tests]:./CONTRIBUTING.md#tests -[unit-tests]:./CONTRIBUTING.md#unit-tests -[integration-tests]:./CONTRIBUTING.md#integration-tests -[linting]:./CONTRIBUTING.md#linting [irc-devtools-html]:irc://irc.mozilla.org/devtools-html diff --git a/bin/chrome-driver.js b/bin/chrome-driver.js new file mode 100644 index 0000000000..0e1b56908d --- /dev/null +++ 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 index fdbdb4e06b..4759c147cf 100644 --- 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 new file mode 100644 index 0000000000..952a5afa91 --- /dev/null +++ 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 self discovery. + +### Playing with the debugger + +Setup the Debugger so that your environment looks like this [gif][debugger-intro-gif]. + +If you have any questions, go back to the [getting setup][getting-setup] +instructions. + + +### Design a new theme :snowflake: + +Lets design a new theme for the debugger, it's not too hard! Our goal here is to style the source tree, editor, and other UI components. + +Share your a screenshot of your theme [here][getting-started-issue]! Here's an example camo [theme][camo-theme] that I designed the other day. + + +### Make breakpoints dance :dancers: + +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. If you come up with something cool, feel free to share it [here][getting-started-issue] and we can add it to the doc! + +### Pausing FTW :red_circle: + +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 ++ } +``` + +### Debugger Philosophy + +Here's the debugger philosophy in a nutshell. + +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! + +Please let us know if we're missing something zen [here][getting-started-issue]. + + +### Next Steps + +Now that you've internalized the debugger philosophy, it's time to start putting this wisdom to use. + +**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][amit-slides] from his [talk][amit-tweet] + +**Contribute back** take a look at how you can [contributing][contributing]. We would love the help! + + + +[contributing]:../CONTRIBUTING.md +[getting-setup]:./getting-setup.md +[getting-started-issue]:https://github.com/devtools-html/debugger.html/issues/1247 + +[debugger-intro-gif]:http://g.recordit.co/WjHZaXKifZ.gif +[amit-slides]:https://docs.google.com/presentation/d/1jdnvL-BwwxEuFbb9tiRxcT6UT-Ua0jGhy9FKBT4b43E/edit +[amit-tweet]:https://twitter.com/amitzur/status/790153843946426369 +[camo-theme]:https://cloud.githubusercontent.com/assets/254562/20683683/ec030354-b57a-11e6-98bc-c8da75721e78.png diff --git a/docs/getting-setup.md b/docs/getting-setup.md new file mode 100644 index 0000000000..52892a9065 --- /dev/null +++ b/docs/getting-setup.md @@ -0,0 +1,170 @@ +## Getting Setup + +![][debugger-intro-gif] + +### Step 1. Install Yarn + +```bash +npm i -g yarn@0.16.1 +``` +*Why Yarn and not NPM?* +NPM installs the latest versions. We use [Yarn][yarn] because we want to make sure everyone is using the same libraries. + +*Why Yarn 0.16.1?* +Yarn is a new tool and it occasionally breaks. + +### Step 2. Install dependencies + +```bash +git clone git@github.com:devtools-html/debugger.html.git +cd debugger.html +yarn install +``` + +*What should I do if I get an error?* +Yarn is still new, please comment on this [issue][yarn-issue] if you see anything weird. + +### Step 3. Open Firefox + +In this step, we'll open Firefox. [Chrome](#starting-chrome) and [Node](#starting-node) are also available in the Appendix. It's not required, but it's generally nice to close other browsers first. + +```bash +yarn run firefox +``` + +After Firefox is open, it's nice to go to a page you want to debug. I recommend, TodoMVC http://todomvc.com/examples/vanillajs/. + +*Why am I opening Firefox from the terminal?* +The firefox command opens firefox with special permissions that enable remote debugging. + +*What should I see?* +Here's a [screenshot][done-screenshot] + +*What should I do if this doesn't work?* +You can either try to run it [manually](#starting-firefox) or comment on the [issue](https://github.com/devtools-html/debugger.html/issues/1341). + +### Step 4. Start the Debugger + +Now that Firefox is open, lets start the development server. In a new terminal tab, run these commands: + +```bash +cd debugger.html +yarn start +``` + +*What does this do?* +This command starts a [development server](../packages/devtools-local-toolbox/README.md). + +### Step 5. Open the Debugger + +Go to `localhost:8000` in any browser to view the Debugger. If everything worked successfully, you should see this [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 yarn@0.16.1 +git clone git@github.com: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 +``` + +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 :)* + +1. 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` + +1. 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][windows-issue] +* [linux][linux-issue] + +**Firefox windows command** +``` +C:\Program Files (x86)\Mozilla Firefox\firefox.exe -start-debugger-server 6080 -P development +``` + +[debugger-intro-gif]:http://g.recordit.co/WjHZaXKifZ.gif +[done-screenshot]:https://cloud.githubusercontent.com/assets/254562/20439409/55e3994a-ad89-11e6-8e76-55e18c7c0d75.png + +[linux-issue]:https://github.com/devtools-html/debugger.html/issues/1082 +[windows-issue]:https://github.com/devtools-html/debugger.html/issues/1248 +[yarn-issue]:https://github.com/devtools-html/debugger.html/issues/1216 +[yarn]:https://yarnpkg.com diff --git a/docs/local-development.md b/docs/local-development.md index 22fbec8b62..a7bea21e5b 100644 --- a/docs/local-development.md +++ b/docs/local-development.md @@ -8,27 +8,92 @@ * [RTL](#rtl) * [Prefs](#prefs) * [Flow](#flow) +* [Logging](#logging) +* [Testing](#testing) + * [Unit Tests](#unit-tests) + * [Integration Tests](#integration-tests) +* [Linting](#linting) + * [Lint JS](#lint-js) + * [Lint CSS](#lint-css) ### Configs -The local toolbox has [configs](../packages/devtools-config/README.md) for runtime configuration. +All default config values are in [`development.json`](../configs/development.json), to override these values you need to [create a local config file](#creating-a-local-config). -**Local Configs** +Here are the most common development configuration options: -You can create a `configs/local.json` file to override development configs. This is great for enabling features locally or changing the theme. Copy the `local-sample` to get started. +* `logging` + * `firefoxProxy` Enables logging the Firefox protocol in the terminal running `yarn start` +* `chrome` + * `debug` Enables listening for remotely debuggable Chrome browsers +* `hotReloading` enables [Hot Reloading](./docs/local-development.md#hot-reloading) of CSS and React + +For a list of all the configuration options see the [packages/devtools-config/README.md](./packages/devtools-config/README.md) + +#### Creating a Local Config + +You can create a `configs/local.json` file to override development configs. This is great for enabling features locally or changing the theme. + +* Copy the `local-sample` to get started. ```bash cp configs/local-sample.json configs/local-sample.json ``` +* Restart your development server by typing `ctrl+c` in the Terminal and run `yarn start` again + +#### Updating your Config + +You can quickly change your local config `configs/local.json`. + +* edit the `configs/local.json` + +```diff +diff --git a/configs/local.json b/configs/local.json +index fdbdb4e..4759c14 100644 +--- a/configs/local.json ++++ b/configs/local.json +@@ -1,6 +1,6 @@ + { + "theme": "light", +- "hotReloading": false, ++ "hotReloading": true, + "logging": { + "actions": false + }, +``` + +* Restart your development server by typing `ctrl+c` in the Terminal and run `yarn start` again + + +### Hot Reloading :fire: + +Hot Reloading watches for changes in the React Components JS and CSS and propagates those changes up to the application without changing the state of the application. You want this turned on. + +To enabled Hot Reloading: + +* [Create a local config file](#creating-a-local-config) if you don't already have one +* edit `hotReloading` + +```diff +diff --git a/configs/local.json b/configs/local.json +index fdbdb4e..4759c14 100644 +--- a/configs/local.json ++++ b/configs/local.json +@@ -1,6 +1,6 @@ + { + "theme": "light", +- "hotReloading": false, ++ "hotReloading": true, + "logging": { + "actions": false + }, +``` -### Hot Reloading +* Restart your development server by typing `ctrl+c` in the Terminal and run `yarn start` again -Hot reloading lets you make changes in React components and CSS and see the changes immediately. -Also, the changes will go into effect without changing the state of app. -Hot reloading does not work all the time, but once you get a sense of its quirks it can be a huge productivity boon. +Read more about [Hot Reloading](./docs/local-development.md#hot-reloading) -It can be turned on by setting `config/local.json` with the contents `{ "hotReloading: true" }`. ### Themes @@ -120,8 +185,6 @@ prefs.clientSourceMapsEnabled = false; We use SVGs in DevTools because they look good at any resolution. - - **Adding a new SVG** * add the SVG in [assets/images](../assets/images) @@ -220,3 +283,89 @@ Rationale: ``` > npm run flow-coverage ``` + +### Logging + +Logging information can be very useful when developing, and there are a few logging options available to you. + +To enable logging: + +* [Create a local config file](#creating-a-local-config) if you don't already have one +* Edit your local config, changing the value of the logger type you want to see to `true` + +```json + "logging": { + "client": false, + "firefoxProxy": false, + "actions": true + } +``` + +* Restart your development server by typing `ctrl+c` in the Terminal and run `yarn start` again + + +Let's cover the logging types. + +* client - This option is currently unused. + +* firefoxProxy - This logger outputs a verbose output of all the Firefox protocol packets to your shell. + +* actions - This logger outputs the Redux actions fired to the browser console. + +### Testing + +Your code must pass all tests to be merged in. Your tests should pass locally before you create a PR and the CI should run an automated test that also passes. + +Here's how can run all the unit tests, lints, and integration tests at once: + +``` +$ yarn run test-all +``` + +#### Unit Tests + +* `yarn test` - Run tests headlessly + * These are the basic unit tests which must always pass +* `yarn run mocha-server` - Run tests in the browser once you open `http://localhost:8003` + * This runs tests in the browser and is useful for fixing errors in the karma tests + +#### Integration tests + +We use [mochitests](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Mochitest) to do integration testing. Running these integration tests locally requires some finesse and so as a contributor we only ask that you run the unit tests. The mochitests will be run by the automated testing which runs once you've made a pull request and the maintainers are happy to help you through any issues which arise from that. + +Learn more about mochitests in our [mochitests docs](./mochitests.md). + + +### Linting + +Run all of lint checks (JS + CSS) run the following command: + +``` +$ yarn run lint +``` + +#### Lint CSS + +We use [Stylelint](http://stylelint.io/) to maintain our CSS styles. The [.stylelintrc](https://github.com/devtools-html/debugger.html/blob/master/.stylelintrc) file contains the style definitions, please adhere to those styles when making changes. + +To test your CSS changes run the command: + +``` +$ yarn run lint-css +``` + +#### Lint JS + +We use [eslint](http://eslint.org/) to maintain our JavaScript styles. The [.eslintrc](https://github.com/devtools-html/debugger.html/blob/master/.eslintrc) file contains our style definitions, please adhere to those styles when making changes. + +To test your JS changes run the command: + +``` +$ yarn run lint-js +``` + +To automatically fix many errors run the command: + +``` +$ yarn run lint-fix +``` diff --git a/package.json b/package.json index e1199717fe..6d20116185 100644 --- a/package.json +++ b/package.json @@ -27,6 +27,7 @@ "mocha-server": "node bin/mocha-server.js", "firefox-unit-test": "node bin/firefox-driver --test", "firefox": "node bin/firefox-driver --start", + "chrome": "node bin/chrome-driver", "mochitests-watch": "MOCHITESTS=true TARGET=firefox-panel webpack --watch", "build-docs": "documentation build --format html --sort-order alpha --shallow --document-exported --output docs/reference/ src/types.js src/utils/ src/reducers/ src/actions/ src/test/mochitest/head.js", "prepush": "npm run lint; node src/test/node-unit-tests.js --dots",