eslint/docs/developer-guide/development-environment.md

   1 # Development Environment
   2
   3 ESLint has a very lightweight development environment that makes updating code fast and easy. This is a step-by-step guide to setting up a local development environment that will let you contribute back to the project.
   4
   5 ## Step 1: Install Node.js
   6
   7 Go to <https://nodejs.org/> to download and install the latest stable version for your operating system.
   8
   9 Most of the installers come with [npm](https://www.npmjs.com/) already installed, but if for some reason it doesn't work on your system, you can install it manually using the instructions on the site.
  10
  11 ## Step 2: Fork and checkout your own ESLint repository
  12
  13 Go to <https://github.com/eslint/eslint> and click the "Fork" button. Follow the [GitHub documentation](https://help.github.com/articles/fork-a-repo) for forking and cloning.
  14
  15 Once you've cloned the repository, run `npm install` to get all the necessary dependencies:
  16
  17 ```
  18 $ cd eslint
  19 $ npm install
  20 ```
  21
  22 You must be connected to the Internet for this step to work. You'll see a lot of utilities being downloaded.
  23
  24 ## Step 3: Add the upstream source
  25
  26 The *upstream source* is the main ESLint repository that active development happens on. While you won't have push access to upstream, you will have pull access, allowing you to pull in the latest code whenever you want.
  27
  28 To add the upstream source for ESLint, run the following in your repository:
  29
  30 ```
  31 git remote add upstream git@github.com:eslint/eslint.git
  32 ```
  33
  34 Now, the remote `upstream` points to the upstream source.
  35
  36 ## Step 4: Install the Yeoman Generator
  37
  38 [Yeoman](http://yeoman.io) is a scaffold generator that ESLint uses to help streamline development of new rules. If you don't already have Yeoman installed, you can install it via npm:
  39
  40     npm install -g yo
  41
  42 Then, you can install the ESLint Yeoman generator:
  43
  44     npm install -g generator-eslint
  45
  46 Please see the [generator documentation](https://github.com/eslint/generator-eslint) for instructions on how to use it.
  47
  48 ## Step 5: Run the tests
  49
  50 Running the tests is the best way to ensure you have correctly set up your development environment. Make sure you're in the `eslint` directory and run:
  51
  52 ```
  53 npm test
  54 ```
  55
  56 The testing takes a few minutes to complete. If any tests fail, that likely means one or more parts of the environment setup didn't complete correctly. The upstream tests always pass.
  57
  58 ## Reference Information
  59
  60 ### Workflow
  61
  62 Once you have your development environment installed, you can make and submit changes to the ESLint source files. Doing this successfully requires careful adherence to our [pull-request submission workflow](contributing/pull-requests.md).
  63
  64 ### Build Scripts
  65
  66 ESLint has several build scripts that help with various parts of development.
  67
  68 #### npm test
  69
  70 The primary script to use is `npm test`, which does several things:
  71
  72 1. Lints all JavaScript (including tests) and JSON
  73 1. Runs all tests on Node.js
  74 1. Checks code coverage targets
  75 1. Generates `build/eslint.js` for use in a browser
  76 1. Runs a subset of tests in PhantomJS
  77
  78 Be sure to run this after making changes and before sending a pull request with your changes.
  79
  80 **Note:** The full code coverage report is output into `/coverage`.
  81
  82 #### npm run lint
  83
  84 Runs just the JavaScript and JSON linting on the repository
  85
  86 #### npm run webpack
  87
  88 Generates `build/eslint.js`, a version of ESLint for use in the browser
  89
  90 #### npm run docs
  91
  92 Generates JSDoc documentation and places it into `/jsdoc`.
  93
  94 #### npm run profile
  95
  96 This command is used for intensive profiling of ESLint using Chrome Developer Tools. It starts a development server that runs through three profiles:
  97
  98 * Large - Runs ESLint on JSHint
  99 * Medium - Runs ESLint on jQuery
 100 * Small - Runs ESLint on KnockoutJS
 101
 102 Your browser should automatically open to the page in question. When that happens:
 103
 104 1. Open up developer tools
 105 1. Click on Profiles
 106
 107 You should start to see profiles for each run show up on the left side. If not, reload the page in the browser. Once all three profiles have completed, they will be available for inspection.