Skip to content

Latest commit

 

History

History
191 lines (144 loc) · 6.65 KB

DEVELOPERS.md

File metadata and controls

191 lines (144 loc) · 6.65 KB
Raw

Installing

In the BitGoJS/ directory:

$ yarn install

Documentation

API and SDK documentation can be found at: https://platform.bitgo.com/.

Pull Requests

Pull requests from third parties are more than welcome! When creating a pull request, a BitGo engineer will be automatically added as a reviewer.

If you notice that the integration test job never runs, don't worry - that's expected. The integration tests use a secret testing password, and so we can't run these tests on untrusted code (PRs from third parties) without reviewing first. Once your code is passing unit tests and has an initial review, a BitGo engineer will re-create your PR and sign your commits, and link back to the original PR.

Things to Avoid

You should not be using the tsc command in terminal. Doing so WITHOUT a tsconfig file (which informs tsc where to install files) would lead to translation files (ending with d.ts and d.ts.map) installed in an incorrect location.

If this happens, navigate to the BitGoJs directory and run git clean -f -d to remove any errant files. Avoid using npm commands and stick with yarn.

Commit Messages

BitGoJS checks all commits against the Conventional Commit Standard, and this is checked by CI when creating new pull requests using commitlint.

To assist with creating valid commit messages, an interactive tool called Commitizen is set up to run as a prepare-commit-msg hook (that is, it will run just before writing a new commit message). Please note that using commitizen is optional, and can be disabled by running rm .git/hooks/prepare-commit-msg from the root of the repository. This can be useful if you are using other tools to author commit messages, and can't use the tool interactively. Commits will still be checked by drone, so creating standard compliant commits is up to the developer if commitizen is not used.

Running tests

Modules typically provide both unit and integration tests.

The rule of thumb for whether a test is a unit test or an integration test is whether or not the test makes a real network request to another system. If it does, it's probably an integration test, otherwise it's a unit test.

You can run unit tests for each individual module:

$ yarn run unit-test --scope bitgo

You can also run unit tests for all modules in parallel:

$ yarn run unit-test

Or just the modules which have changed since master:

$ yarn run unit-test-changed

Or the file that contains a specific string

  • if you are a specific module:
$ yarn run unit-test --grep"keyword"
  • if you are in the BitGoJs/ top-level directory
$ yarn run unit-test -- -- --grep "keyword"

Note: Each module's output will be prefixed with it's name, but it may be difficult to unmangle the test output.

To aid with evaluating test results, and especially test failures, a fancy test report is generated by the CI system and uploaded to S3.

The link to this report is output in the "upload reports" stage of each build pipeline.

Here is an example of this output:

@bitgo/express: === TEST REPORT UPLOADED SUCCESSFULLY ===
@bitgo/express: https://bitgo-sdk-test-reports.s3.amazonaws.com/1036/express/unit tests (node:6).html

Working with modules

Should I make a new module for my contribution?

This is a question you should ask before making large changes to the SDK. The original goal of modularizing the SDK was to allow users to only include support for the features they actually want to use, instead of bringing in hundreds of megabytes of dependencies which they won't use.

Therefore, if your feature meets the following criteria, then it is a good candidate for being its own module. Otherwise, perhaps not.

  1. Will this feature require additional dependencies to be added? How heavy are those dependencies?
  2. Is this feature something which would only be used by a small fraction of SDK users?
  3. Is this feature extending existing bitgo functionality, or is it providing entirely new functionality? For example, adding a new coin would be extending existing bitgo functionality.

These recommendations are just that, recommendations. Please use your best judgement when it comes to how your change is architected.

Module Configuration

Each module should have the following basic file structure:

- modules/
  - mymodule/
    - src/
      - index.ts
    - test/
      - unit/
        - test-feature.ts
      - integration/
        - test-feature.ts
    - package.json
    - README.md

package.json

  • name

For a binary application module named "fooapp", this should be set to @bitgo/fooapp.

For a generic library module named "bar", this should be set to @bitgo/sdk-lib-bar.

For a coin library module which supports a coin with ticker "BAZ", this should be set to @bitgo/sdk-coin-baz.

  • scripts

These npm scripts may be run during lifecycle events and by lerna across all modules. If a script is not present in a module, that module will be skipped.

Name Description Required?
test / unit-test Run module unit tests Yes
integration-test Run module integration tests. These are run when a PR is targeted to merge against master. No
prepare / build Compile typescript sources No
clean Clean up generated build files No
audit Run a vulnerability against the module dependencies Yes
gen-coverage Generate a code coverage report No
upload-coverage Upload a code coverage report No
upload-artifacts Upload any artifacts produced by the build and test process No

Additional scripts which are too large for the package.json file should be placed in scripts/ and should be plain javascript or bash.

  • repository

This shall always be set for all modules to:

{
  "repository": {
    "type": "git",
    "url": "https://github.com/BitGo/BitGoJS.git"
  }
}

  • license

License shall be Apache-2.0.

  • engines

Engines should be set to the following:

{
  "engines": {
    "node": ">=6.12.3 <13.0.0",
    "npm": ">=3.10.10"
  }
}

tsconfig.json

There are a few things each module's tsconfig.json must do:

  • Extend the root tsconfig.json
  • Set the outDir and rootDir compiler options
  • Set the include property to the correct module source directories (package.json should also be included if it is read at runtime)

Here is a template to help get started:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "."
  },
  "include": [
    "src/**/*",
    "package.json"
  ]
}