Updated CONTRIBUTING.md (#794)

As titled, also renamed the script files for a better DX.

Author: delvedor

CONTRIBUTING.md

@@ -31,11 +31,7 @@ Once your changes are ready to submit for review:
 1. Test your changes
 
     Run the test suite to make sure that nothing is broken.
-    Usually run `npm test` is enough, our CI will take care of running the integration test.
-    If you want to run them on your own, you should spin up and Elasticsearch instance via the scripts that you
-    can find inside the `scripts` folder, and then run `npm run test:integration`.<br/>
-    If you want to run the integration test for the Elastic licensed APIs, you should run the `platinum` script, and
-    then run `TEST_ES_SERVER=https://elastic:changeme@localhost:9200 npm run test:integration`.
+    Usually run `npm test` is enough, our CI will take care of running the integration test. If you want to run the integration test yourself, see the *Testing* section below.
 
 2. Submit a pull request
 
@@ -60,6 +56,39 @@ Once your changes are ready to submit for review:
     but we'll do our best to dedicate it the attention it deserves.
     Your effort is much appreciated!
 
+### Code generation
+
+The entire content of the API folder is generated as well as the `docs/reference.asciidoc` file.<br/>
+If you want to run the code generation you should run the following command:
+```sh
+node scripts/generate --tag <tag name>
+# or
+node scripts/generate --branch <branch name>
+```
+Then you should copy the content of `api/generated.d.ts` into the `index.d.ts` file *(automate this step would be a nice pr!)*.
+
+### Testing
+There are different test scripts, usually during development you only need to run `npm test`, but if you want you can run just a part of the suite, following you will find all the testing scripts and what they do.
+
+| Script | Description |
+|---|---|
+| `npm run test:unit` | Runs the content of the `test/unit` folder. |
+| `npm run test:behavior` | Runs the content of the `test/behavior` folder. |
+| `npm run test:types` | Runs the content of the `test/types` folder. |
+| `npm run test:unit -- --cov --coverage-report=html` | Runs the content of the `test/unit` folder and calculates the code coverage. |
+| `npm run test:integration` | Runs the integration test runner.<br/>*Note: it requires a living instance of Elasticsearch.* |
+| `npm run lint` | Run the [linter](https://standardjs.com/). |
+| `npm run lint:fix` | Fixes the lint errors. |
+| `npm test` | Runs lint, unit, behavior, and types test. |
+
+#### Integration test
+The integration test are generated on the fly by the runner you will find inside `test/integration`, once you execute it, it will clone the Elasticsearch repository and checkout the correct version to grab the [OSS yaml files](https://github.com/elastic/elasticsearch/tree/master/rest-api-spec/src/main/resources/rest-api-spec/test) and the [Elastic licensed yaml files](https://github.com/elastic/elasticsearch/tree/master/x-pack/plugin/src/test/resources/rest-api-spec/test) that will be used for generating the test.
+
+Usually this step is executed by CI since it takes some time, but you can easily run this yourself! Just follow this steps:
+1. Boot an Elasticsearch instance, you can do that by running `./scripts/es-docker.sh` or `./scripts/es-docker-platinum.sh`, the first one will work only with the OSS APIs, while the second will work also with the Elastic licensed APIs;
+1. If you are running the OSS test, you should use `npm run test:integration`, otherwise use `TEST_ES_SERVER=https://elastic:changeme@localhost:9200 npm run test:integration`. You can also pass a `-b` parameter if you want the test to bail out at the first failure: `npm run test:integration -- -b`;
+1. Grab a coffee, it will take some time ;)
+
 ### Releasing
 
 If you have access to make releases, the process is as follows:

package.json

@@ -21,7 +21,6 @@
     "test:behavior": "tap test/behavior/*.test.js -J -t 300",
     "test:integration": "tap test/integration/index.js -T --harmony --no-esm",
     "test:types": "tsc --project ./test/types/tsconfig.json",
-    "test:benchmarks": "nanobench test/benchmarks/*.bench.js",
     "test:coverage": "nyc npm run test:unit && nyc report --reporter=text-lcov > coverage.lcov && codecov",
     "lint": "standard",
     "lint:fix": "standard --fix",

scripts/run.js renamed to scripts/generate.js

@@ -19,10 +19,10 @@
 
 'use strict'
 
-const generate = require('./generate')
+const generate = require('./generateApis')
 const generateRequestTypes = require('./generateRequestTypes')
 const cloneAndCheckout = require('./clone-es')
-const genFactory = require('./genMain')
+const genFactory = require('./generateMain')
 const generateDocs = require('./generateDocs')
 
 module.exports = {