👍🎉 First off, thanks for taking the time to contribute! 🎉👍

We respect your time and want to help you make the most of it as you learn more about this project.

What should I know before I get started?

• debugger.html
• devtools.html
• Firefox Developer Tools

Getting Started

• Web Application
• Debuggable Targets
  • Firefox Remote Debugging
  • Chrome Remote Debugging
  • Node.js Remote Debugging

How Can I Contribute?

• Reporting Bugs
• Suggesting Enhancements
• Writing Documentation
• Writing Code
  • Your First Code Contribution
  • Coding Standards
  • Pull Requests
  • Hot Reloading
• Tests
  • Unit Tests
  • Integration Tests
  • Linting
  • Storybook
• Configuration
  • Create a local config file
• Issues and Pull Request labels

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. Mozilla also has a set of participation guidelines which goes into greater detail specific to Mozilla employees and contributors.

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.

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.

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 and take a look at the devtools.html meta bug for tracking progress.

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.

The debugger.html is a web application that makes a WebSocket 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.

First we need to get the web application running. Within the source code directory, from the command line run these commands.

• npm install - Install dependencies
• npm start - Start development web server

Then, because npm start will remain running, from another terminal window you can open http://localhost:8000 in your browser or type the following:

• open http://localhost:8000 - Open in any modern browser

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.

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.

$ npm run firefox

• Restart your development server ctrl+c in the Terminal and run npm start again
• Reload localhost:8000 (you should now see a Firefox tabs section)

Command line option

Here are the instructions for running Firefox from the command line:

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

NOTE: The Firefox started from the npm 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.

• 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.

Start by running Chrome with remote debugging turned on, this command also creates a new temporary profile

/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

Now turn on Chrome debugging in the config by creating a local config file

• Edit the config/local.json you just created to change the value of chrome.debug to be true

"chrome": {
  "debug": true
}

• Restart your development server by typing ctrl+c in the Terminal and run npm start again
• Reload localhost:8000 (you should now see a Chrome tabs section)

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

Here is a great GitHub guide on contributing to Open Source to help you get started.

If you find an issue with the code please do file an issue and tag it with the label bug. We'll do our best to review the issue in a timely manner and respond.

We are actively investigating ways of support enhancement requests in the project so these instructions are subject to change. For now please create an issue, tag it with the enhancement label and we will attempt to respond.

Documentation is as important as code and we need your help to maintain clear and usable documentation. If you find an error in here or other project documentation please file an issue and tag it with the label docs.

We have a number of tools to help you with your code contributions, the following describes them all and how you can make use of them.

If you've contributed to an open source project before and would like to help this one please take a look through the up for grabs issues:

• up for grabs - issues should have clear requirements and a difficulty level set as a label

If you find an up for grabs issue without a difficulty level set as a label or unclear requirements please comment in the issue so we can get that fixed.

If this is your first time contributing any code to an open source project take a look through the first-timers-only issues:

• first-timers-only - issues which should have clear expectations and a mentor to help you through

If you didn't find any issues this time, don't worry. Take a look at the up for grabs issues above and let someone know this is your first time contributing code.

To begin your work make sure you follow these steps:

• Fork this project
• Create a branch to start your work git checkout -b your-feature-name
• Commit your work
• Create a pull request

Be consistent with the rest of the code in the file

Here are pointers to the DevTools general coding style and formatting guidelines.

• JS Coding Style
• Formatting Comments

We use issues and milestones for planning purposes as well as tracking bugs.

Keep Issues Relevant

We try to keep the number of open issues to a minimum. If work isn't going to be done in a timely manner we would rather close the issue than let them go stale. Closed issues can always be reopened again when we are ready to start the work. This process helps keep the focus of the project more understandable to others.

Intent to implement

When a person is assigned to an issue this indicates an intent to implement. Please ask within the issue if you would like to work on a fix so multiple people don't create pull requests for it.

• Include screenshots and animated GIFs in your pull request whenever possible.
• List any steps necessary to trigger the feature you've created or bug you are fixing
• Always run the tests locally before creating your PR
• Request review from @jasonLaster or @jlongster by mentioning their names in the PR

Working on your first Pull Request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub

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 if you don't already have one
• Edit the config/local.json you just created to change the value of hotReloading to be true

{
  "hotReloading": true
}

• Restart your development server by typing ctrl+c in the Terminal and run npm start again

Read more about Hot Reloading

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:

$ npm run test-all

• npm test - Run tests headlessly
• These are the basic unit tests which must always pass
• npm 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

We use mochitests 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.

Run all of lint checks (JS + CSS) run the following command:

$ npm run lint

We use Stylelint to maintain our CSS styles. The .stylelintrc file contains the style definitions, please adhere to those styles when making changes.

To test your CSS changes run the command:

$ npm run lint-css

We use eslint to maintain our JavaScript styles. The .eslintrc file contains our style definitions, please adhere to those styles when making changes.

To test your JS changes run the command:

$ npm run lint-js

Storybook is our local development and testing utility that allows you to see how an individual component like the breakpoint list view or the call stack view react to any changes to style and code you've made.

$ npm run storybook

Read more information in storybook docs

All default config values are in config/development.json, to override these values you need to create a local config file.

Here are the most common development configuration options:

• logging
  • firefoxProxy Enables logging the Firefox protocol in the terminal running npm start
• chrome
  • debug Enables listening for remotely debuggable Chrome browsers
• hotReloading enables Hot Reloading of CSS and React

For a list of all the configuration options see the config/README

• Copy the config/development.json to config/local.json

These are the labels we use to help organize and communicate the state of issues and pull requests in the project. If you find a label being used that isn't described here please file an issue to get it listed.