chore: speed up builds (#1748)

.github/workflows/docs.yml

@@ -11,11 +11,14 @@ jobs:
       - name: Checkout 🛎️
         uses: actions/checkout@v2
 
-      - name: Install and Build 🔧
-        run: |
+      - name: Install Dependencies
           npm install --ignore-scripts
-          npx lerna bootstrap --scope @opentelemetry/api --include-filtered-dependencies
-          npm run docs
+          npx lerna bootstrap --no-ci --scope @opentelemetry/api --include-dependencies
+
+      - name: Build 🔧
+        run: |
+          npx lerna run compile --scope @opentelemetry/api
+          npx lerna run docs
 
       - name: Deploy 🚀
         uses: JamesIves/github-pages-deploy-action@releases/v3

.github/workflows/lint.yml

@@ -48,8 +48,15 @@ jobs:
           npm run lint
           npm run lint:examples
 
-      - name: Install and Build API Dependencies
-        run: npx lerna bootstrap --no-ci --scope @opentelemetry/api --include-filtered-dependencies
+      - name: Install API Dependencies
+        run: |
+          npm install --ignore-scripts
+          npx lerna bootstrap --no-ci --scope @opentelemetry/api --include-dependencies
+
+      - name: Build 🔧
+        run: |
+          npx lerna run compile --scope @opentelemetry/api
+          npx lerna run docs
 
       - name: Test Docs
         run: npm run docs-test

.github/workflows/unit-test.yml

@@ -30,6 +30,8 @@ jobs:
         run: npm install --ignore-scripts
       - name: Boostrap Dependencies
         run: npx lerna bootstrap --no-ci
+      - name: Build
+        run: npm run compile
       - name: Unit tests
         run: npm run test
       - name: Report Coverage
@@ -58,6 +60,8 @@ jobs:
         run: npm install --ignore-scripts
       - name: Boostrap Dependencies
         run: npx lerna bootstrap --no-ci
+      - name: Build
+        run: npm run compile
       - name: Unit tests
         run: npm run test:browser
       - name: Report Coverage

.github/workflows/w3c-integration-test.yml

@@ -12,10 +12,14 @@ jobs:
       - name: Checkout 🛎️
         uses: actions/checkout@v2
 
-      - name: Install and Build 🔧
+      - name: Install
         run: |
           npm install --ignore-scripts
-          npx lerna bootstrap --scope=propagation-validation-server --include-dependencies
+          npx lerna bootstrap --no-ci --scope=propagation-validation-server --include-dependencies
+      
+      - name: Build 🔧
+        run: npm run compile 
+        working-directory: ./integration-tests/propagation-validation-server
 
       - name: Run W3C Test harness
         run: ./integration-tests/tracecontext-integration-test.sh

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
 

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.
 

backwards-compatability/node10/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.es5.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "build"
+  },
+  "include": [
+    "index.ts"
+  ],
+  "references": [
+    {
+      "path": "../../packages/opentelemetry-sdk-node"
+    },
+    {
+      "path": "../../packages/opentelemetry-tracing"
+    }
+  ]
+}

backwards-compatability/node12/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.es5.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "build"
+  },
+  "include": [
+    "index.ts"
+  ],
+  "references": [
+    {
+      "path": "../../packages/opentelemetry-sdk-node"
+    },
+    {
+      "path": "../../packages/opentelemetry-tracing"
+    }
+  ]
+}

backwards-compatability/node8/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.es5.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "build"
+  },
+  "include": [
+    "index.ts"
+  ],
+  "references": [
+    {
+      "path": "../../packages/opentelemetry-sdk-node"
+    },
+    {
+      "path": "../../packages/opentelemetry-tracing"
+    }
+  ]
+}

integration-tests/propagation-validation-server/package.json

@@ -7,6 +7,9 @@
   "repository": "open-telemetry/opentelemetry-js",
   "author": "OpenTelemetry Authors",
   "license": "Apache-2.0",
+  "scripts": {
+    "compile": "tsc --build"
+  },
   "dependencies": {
     "@opentelemetry/api": "^0.14.0",
     "@opentelemetry/context-async-hooks": "^0.14.0",
@@ -15,5 +18,8 @@
     "axios": "0.21.0",
     "body-parser": "1.19.0",
     "express": "4.17.1"
+  },
+  "devDependencies": {
+    "typescript": "3.9.7"
   }
 }

integration-tests/propagation-validation-server/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "build"
+  },
+  "include": [],
+  "references": [
+    {
+      "path": "../../packages/opentelemetry-api"
+    },
+    {
+      "path": "../../packages/opentelemetry-context-async-hooks"
+    },
+    {
+      "path": "../../packages/opentelemetry-core"
+    },
+    {
+      "path": "../../packages/opentelemetry-tracing"
+    }
+  ]
+}

package.json

@@ -5,20 +5,21 @@
   "main": "build/src/index.js",
   "types": "build/src/index.d.ts",
   "scripts": {
+    "compile": "tsc --build",
+    "watch": "tsc --build --watch",
+    "clean": "tsc --build --clean",
     "bench": "node benchmark",
-    "clean": "lerna run clean",
-    "postinstall": "npm run bootstrap",
-    "precompile": "tsc --version",
+    "postinstall": "update-ts-references && npm run bootstrap",
+    "postcompile": "npm run submodule && npm run protos:copy",
+    "submodule": "git submodule sync --recursive && git submodule update --init --recursive",
+    "protos:copy": "lerna run protos:copy",
     "version:update": "lerna run version:update",
-    "compile": "lerna run compile",
     "test": "lerna run test",
     "test:browser": "lerna run test:browser",
     "test:backcompat": "lerna run test:backcompat",
     "bootstrap": "lerna bootstrap",
-    "bump": "lerna publish",
     "codecov": "lerna run codecov",
     "codecov:browser": "lerna run codecov:browser",
-    "changelog": "lerna-changelog",
     "predocs-test": "npm run docs",
     "docs-test": "lerna run docs-test",
     "docs": "lerna run docs",
@@ -57,7 +58,8 @@
     "lerna": "3.22.1",
     "lerna-changelog": "1.0.1",
     "markdownlint-cli": "0.25.0",
-    "typescript": "3.9.7"
+    "typescript": "3.9.7",
+    "update-ts-references": "^1.3.0"
   },
   "husky": {
     "hooks": {