chore: document development cycle

open-telemetry · Dec 17, 2020 · e96e138 · e96e138
1 parent 8fccf1f
commit e96e138
Show file tree

Hide file tree

Showing 34 changed files with 486 additions and 30 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,6 +2,19 @@
 
 We'd love your help!
 
+## Development Quick Start
+
+To get the project started quickly, you can follow these steps. For more
+detailed instructions, see [development](#development) below.
+
+```sh
+$ git clone https://github.com/open-telemetry/opentelemetry-js.git
+$ cd opentelemetry-js
+$ npm install
+$ npm run compile
+$ npm test
+```
+
 ## Report a bug or requesting feature
 
 Reporting bugs is an important contribution. Please make sure to include:
@@ -57,15 +70,102 @@ Remember to always work in a branch of your local copy, as you might otherwise h
 
 Please also see [GitHub workflow](https://github.com/open-telemetry/community/blob/master/CONTRIBUTING.md#github-workflow) section of general project contributing guide.
 
-### Running the tests
+## Development
+
+### Tools used
+
+- [NPM](https://npmjs.com)
+- [TypeScript](https://www.typescriptlang.org/)
+- [lerna](https://github.com/lerna/lerna) to manage dependencies, compilations, and links between packages. Most lerna commands should be run by calling the provided npm scripts.
+- [MochaJS](https://mochajs.org/) for tests
+- [gts](https://github.com/google/gts)
+- [eslint](https://eslint.org/)
+
+Most of the commands needed for development are accessed as [npm scripts](https://docs.npmjs.com/cli/v6/using-npm/scripts). It is recommended that you use the provided npm scripts instead of using `lerna run` in most cases.
+
+### Install dependencies
+
+This will install all dependencies for the root project and all modules managed by `lerna`. By default, a `postinstall` script will run `lerna bootstrap` automatically after an install. This can be avoided using the `--ignore-scripts` option if desired.
+
+```sh
+$ npm install
+```
+
+### Compile modules
+
+All modules are managed as a composite typescript project using [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html). This means that a breaking change in one module will be reflected in compilations of its dependent modules automatically.
+
+DO NOT use lerna to compile all modules unless you know what you are doing because this will cause a new typescript process to be spawned for every module in the project.
+
+```sh
+# Build all modules
+$ npm run compile
+
+# Remove compiled output
+$ npm run clean
+```
+
+These commands can also be run for specific packages instead of the whole project, which can speed up compilations while developing.
+
+```sh
+# Build a single module and all of its dependencies
+$ cd packages/opentelemetry-module-name
+$ npm run compile
+```
+
+Finally, builds can be run continuously as files change using the `watch` npm script.
+
+```sh
+# Build all modules
+$ npm run watch
+
+# Build a single module and all of its dependencies
+$ cd packages/opentelemetry-module-name
+$ npm run watch
+```
+
+### Running tests
+
+Similar to compilations, tests can be run from the root to run all tests or from a single module to run only the tests for that module.
+
+```sh
+# Test all modules
+$ npm test
+
+# Test a single module
+$ cd packages/opentelemetry-module-name
+$ npm test
+```
+
+### Linting
+
+This project uses a combination of `gts` and `eslint`. Just like tests and compilation, linting can be done for all packages or only a single package.
+
+```sh
+# Lint all modules
+$ npm lint
+
+# Lint a single module
+$ cd packages/opentelemetry-module-name
+$ npm lint
+```
+
+There is also a script which will automatically fix many linting errors.
+
+```sh
+# Lint all modules, fixing errors
+$ npm lint:fix
+
+# Lint a single module, fixing errors
+$ cd packages/opentelemetry-module-name
+$ npm lint:fix
+```
+
+### Adding a package
 
-The `opentelemetry-js` project is written in TypeScript.
+To add a new package, copy `packages/template` to your new package directory and modify the `package.json` file to reflect your desired package settings. If the package will not support browser, the `karma.conf` file may be deleted. If the package will support es5 targets, the reference to `tsconfig.base.json` in `tsconfig.json` should be changed to `tsconfig.es5.json`.
 
-- `npm install` to install dependencies.
-- `npm run compile` compiles the code, checking for type errors.
-- `npm run bootstrap` Bootstrap the packages in the current Lerna repo. Installs all of their dependencies and links any cross-dependencies.
-- `npm test` tests code the same way that our CI will test it.
-- `npm run lint:fix` lint (and maybe fix) any changes.
+After adding the package, run `npm install` from the root of the project. This will update the `tsconfig.json` project references automatically and install all dependencies in your new package.
 
 ### Guidelines for Pull Requests
 

diff --git a/README.md b/README.md
@@ -120,8 +120,9 @@ estimates, and subject to change.
 ## Contributing
 
 We'd love your help!. Use tags [up-for-grabs][up-for-grabs-issues] and
-[good first issue][good-first-issues] to get started with the project. Follow
-[CONTRIBUTING](CONTRIBUTING.md) guide to report issues or submit a proposal.
+[good first issue][good-first-issues] to get started with the project. For 
+instructions to build and make changes to this project, see the
+[CONTRIBUTING](CONTRIBUTING.md) guide.
 
 We have a weekly SIG meeting! See the [community page](https://github.com/open-telemetry/community#javascript-sdk) for meeting details and notes.
 

diff --git a/package.json b/package.json
@@ -6,6 +6,7 @@
   "types": "build/src/index.d.ts",
   "scripts": {
     "compile": "tsc --build",
+    "watch": "tsc --build --watch",
     "clean": "tsc --build --clean",
     "bench": "node benchmark",
     "postinstall": "update-ts-references && npm run bootstrap",

diff --git a/packages/opentelemetry-api/package.json b/packages/opentelemetry-api/package.json
@@ -22,7 +22,7 @@
     "version": "node ../../scripts/version-update.js",
     "docs-test": "linkinator docs/out --silent --skip david-dm.org",
     "docs": "typedoc --tsconfig tsconfig.docs.json",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-context-base/package.json b/packages/opentelemetry-context-base/package.json
@@ -14,7 +14,7 @@
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-context-zone-peer-dep/package.json b/packages/opentelemetry-context-zone-peer-dep/package.json
@@ -14,7 +14,7 @@
     "version": "node ../../scripts/version-update.js",
     "tdd": "karma start",
     "test:browser": "nyc karma start --single-run",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-context-zone/package.json b/packages/opentelemetry-context-zone/package.json
@@ -11,7 +11,7 @@
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-core/package.json b/packages/opentelemetry-core/package.json
@@ -22,7 +22,7 @@
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-exporter-collector/package.json b/packages/opentelemetry-exporter-collector/package.json
@@ -20,7 +20,7 @@
     "test": "nyc ts-mocha -p tsconfig.json 'test/**/*.test.ts' --exclude 'test/browser/**/*.ts'",
     "test:browser": "nyc karma start --single-run",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-exporter-jaeger/package.json b/packages/opentelemetry-exporter-jaeger/package.json
@@ -14,7 +14,7 @@
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-exporter-prometheus/package.json b/packages/opentelemetry-exporter-prometheus/package.json
@@ -14,7 +14,7 @@
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-exporter-zipkin/package.json b/packages/opentelemetry-exporter-zipkin/package.json
@@ -20,7 +20,7 @@
     "test": "nyc ts-mocha -p tsconfig.json 'test/**/*.test.ts' --exclude 'test/browser/**/*.ts'",
     "test:browser": "nyc karma start --single-run",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-instrumentation-http/package.json b/packages/opentelemetry-instrumentation-http/package.json
@@ -14,7 +14,7 @@
     "lint:fix": "eslint . --ext .ts --fix",
     "codecov": "nyc report --reporter=json && codecov -f coverage/*.json -p ../../",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-instrumentation-xml-http-request/package.json b/packages/opentelemetry-instrumentation-xml-http-request/package.json
@@ -14,7 +14,7 @@
     "version": "node ../../scripts/version-update.js",
     "tdd": "karma start",
     "test:browser": "nyc karma start --single-run",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-instrumentation/package.json b/packages/opentelemetry-instrumentation/package.json
@@ -39,7 +39,7 @@
     "test": "nyc ts-mocha -p tsconfig.json 'test/**/*.test.ts' --exclude 'test/browser/**/*.ts'",
     "test:browser": "nyc karma start --single-run",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-metrics/package.json b/packages/opentelemetry-metrics/package.json
@@ -14,7 +14,7 @@
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-node/package.json b/packages/opentelemetry-node/package.json
@@ -14,7 +14,7 @@
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-plugin-fetch/package.json b/packages/opentelemetry-plugin-fetch/package.json
@@ -14,7 +14,7 @@
     "version": "node ../../scripts/version-update.js",
     "tdd": "karma start",
     "test:browser": "nyc karma start --single-run",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "fetch",

diff --git a/packages/opentelemetry-plugin-http/package.json b/packages/opentelemetry-plugin-http/package.json
@@ -14,7 +14,7 @@
     "lint:fix": "eslint . --ext .ts --fix",
     "codecov": "nyc report --reporter=json && codecov -f coverage/*.json -p ../../",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-propagator-b3/package.json b/packages/opentelemetry-propagator-b3/package.json
@@ -13,7 +13,7 @@
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-sdk-node/package.json b/packages/opentelemetry-sdk-node/package.json
@@ -13,7 +13,7 @@
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-semantic-conventions/package.json b/packages/opentelemetry-semantic-conventions/package.json
@@ -13,7 +13,7 @@
     "test": "nyc ts-mocha -p tsconfig.json 'test/**/*.test.ts'",
     "tdd": "npm run test -- --watch-extensions ts --watch",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-tracing/package.json b/packages/opentelemetry-tracing/package.json
@@ -21,7 +21,7 @@
     "lint:fix": "eslint . --ext .ts --fix",
     "codecov": "nyc report --reporter=json && codecov -f coverage/*.json -p ../../",
     "version": "node ../../scripts/version-update.js",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/opentelemetry-web/package.json b/packages/opentelemetry-web/package.json
@@ -14,7 +14,7 @@
     "version": "node ../../scripts/version-update.js",
     "tdd": "karma start",
     "test:browser": "nyc karma start --single-run",
-    "watch": "tsc -w"
+    "watch": "tsc --build --watch"
   },
   "keywords": [
     "opentelemetry",

diff --git a/packages/template/.eslintignore b/packages/template/.eslintignore
@@ -0,0 +1,2 @@
+build
+
diff --git a/packages/template/.eslintrc.js b/packages/template/.eslintrc.js
@@ -0,0 +1,9 @@
+module.exports = {
+    "env": {
+        "mocha": true,
+        "commonjs": true,
+        "node": true,
+        "browser": true
+    },
+    ...require('../../eslint.config.js')
+}
diff --git a/packages/template/.npmignore b/packages/template/.npmignore
@@ -0,0 +1,4 @@
+/bin
+/coverage
+/doc
+/test