Skip to content

BUILD.md

Latest commit

 

History

History
110 lines (63 loc) · 5.83 KB

BUILD.md

File metadata and controls

110 lines (63 loc) · 5.83 KB

Build Considerations: Project Root

yarn is used instead of npm.

package.json

Dependencies (dev and otherwise)

@typescript-eslint/eslint-plugin

ESLint is being used to lint the repo, as a whole. Within ./packages/plexus (for now), @typescript-eslint/eslint-plugin is used to apply ESLint to TypeScript. This application is localized to plexus via configuring ./packages/plexus/.eslintrc.js for TypeScript, which means the change in settings is only applied to subdirectories of ./packages/plexus. This package works really well, but there are quite a few issues it doesn't catch. For that, we use the TypeScript compiler.

typescript

In the project root, typescript is used to bolster the linting of TypeScript files. tsc catches quite a few issues that ESLint does not pick up on.

In ./packages/plexus, typescript is used to generate type declarations for the ES module build. See ./packages/plexus/BUILD.md for details.

Scripts

build

lerna run build executes the build in each of ./packages/* sub-packages.

eslint

This applies ESLint to the repo, as a whole. The TypeScript linting has a distinct configuration, which is a descendent of ./.eslintrc.js. See TypeScript, above.

lint

This is an amalgamation of linting scripts that run to make sure things are all-good. It's run in CI (travis) and as part of a pre-commit hook.

  • prettier-lint
  • tsc-lint
  • eslint
  • check-license

prepare

Runs after the top-level yarn install. This ensures ./packages/plexus builds and is available to ./packages/jaeger-ui.

prettier-comment, prettier, prettier-lint

prettier-comment is just an explanation for why the ./node_module/.bin/bin-prettier.js path is used instead of just yarn prettier etc; it's due to an issue with yarn.

prettier formats the code.

prettier-lint runs bin-prettier in the --list-different mode, which only outputs filenames if they would be changed by prettier formatting. If any such files are encountered, the program exits with a non-zero code. This is handy for blocking CI and pre-commits.

tsc-lint, tsc-lint-debug

tsc is run with the --noEmit option to bolster linting of TypeScript files. See TypeScript, above.

tsc-lint-debug is for diagnosing problems with linking, resolving files, or aliases in TypeScript code. It lists the files involved in the compilation.

test

test runs tests for all packages.

Note that ./packages/plexus does not yet have any tests, as tracked in issue #340.

./packages/jaeger-ui uses Jest for testing. It can be useful to directly run tests for that package by running yarn test from its directory, rather than the repository root.

Tests for React components in ./packages/jaeger-ui make extensive use of Jest's snapshot testing functionality. These snapshots can be regenerated by running yarn test -u from the package directory to regenerate all snapshots, or yarn test -u --testNamePattern <test name> to regenerate snapshots for a subset of tests only.

husky . hooks . pre-commit

Runs the lint and test scripts.

.eslintrc.js

Pretty basic.

Note: This configuration is extended by ./packages/plexus/.eslintrc.js.

.github/workflows

Holds GitHub Actions workflows used in CI and in release.

CodeCov is integrated into the unit tests workflow to report coverage data from ./packages/jaeger-ui. When unit tests are added to Plexus, this integration will need to be updated to gather coverage data for Plexus as well.

yarn install --frozen-lockfile ensures installs in CI fail if they would typically mutate the lockfile.

lerna.json

We should probably audit our use of lerna to make sure a) it's necessary and b) it's idiomatic if it is necessary. We have ended up relying quite a bit on yarn workspaces, which has reduced the relevance of lerna. (Ticket)

tsconfig.json

Used to configure the tsc-lint script and, in theory, the IDE (such as VS Code).

A few notable compiler settings:

  • lib
  • skipLibCheck - Maybe worth reevaluating in the future
  • strict - Important
  • noEmit - We're using this for linting, after all
  • include - We've included ./typgings here because it turned out to be a lot simpler than configuring types, typeRoots and paths

typings/{custom.d.ts, index.d.ts}

This is relevant for ./packages/plexus/src/LayoutManager/getLayout.tsx and the viz.js package.

I wasn't able to get much in the line of error messaging, so I'm pretty vague on this.

The version of viz.js in use (1.8.1) ships with an index.d.ts file, but it has some issues. ./typings/custom.d.ts defines an alternate type declaration for viz.js by targeting viz.js/viz.js. It was necessary use ./typings/index.d.ts to refer to ./typings/custom.d.ts. Then, importing the modules main file, which is viz.js/viz.js, will use the alternate type declaration.