Skip to content

Latest commit

 

History

History
121 lines (78 loc) · 4.39 KB

CONTRIBUTING.md

File metadata and controls

121 lines (78 loc) · 4.39 KB
Raw

How to contribute to Buidler

This document contains some tips on how to collaborate in this project.

Project structure

This repository is a monorepo handled with Lerna.

There's a folder for each subproject in packages/. All of them are plugins, except for /packages/buidler-core which is the main project (i.e. the one that's published as @nomiclabs/buidler).

Installing

To install this project you have to run:

  1. npm install

Building the projects

Plugins require buidler-core to be built or tested. Our recommendation is to run npm run watch from the root folder. This will keep everything compiled, and these problems will be avoided.

Testing

All tests are written using mocha and chai.

Per-package

You can run a package's tests by executing npm test inside its folder.

Note: for package buidler-vyper case, a running instance of Docker Desktop is required, with ethereum/vyper image pulled. To install it, run:

docker pull ethereum/vyper:0.1.0b10

Entire project

You can run all the tests at once by running npm test from the root folder.

For the case of package buidler-vyper, an ethereum/vyper docker instance installed is required (see previous section for details). Exception of this requirement is if running on a Windows local machine, in this case we skip it by default since Win 10 Pro version would be also required.

Code formatting

We use Prettier to format all the code without any special configuration. Whatever Prettier does is considered The Right Thing. It's completely fine to commit non-prettied code and then reformat it in a later commit.

We also have tslint installed in all the projects. It checks that you have run Prettier and forbids some dangerous patterns.

The linter is always run in the CI, so make sure it passes before pushing code. You can use npm run lint and npm run lint:fix inside the packages' folders.

Branching

We work on the branch development and keep master in sync with the latest release.

Please, branch from development when implementing a new feature or fixing a bug, and use it as the base branch in every pull request.

Dependencies

We keep our dependencies versions in sync between the different projects.

Running node scripts/check-dependencies.js from the root folder checks that every project specifies the same versions of each dependency. It will print an error if the versions get out of sync.

Performance and dependencies loading

Buidler and its plugins are optimized for keeping startup time low.

This is done by selectively requiring dependencies when needed using import or require following this criteria:

  1. If something is only imported for its type, and NOT its value, use a top-level import ... from "mod"
  2. If a module is in the least below, use a top-level import ... from "mod"".
  3. Otherwise, use await import or require locally in the functions that use it.
    1. If the function is sync, use node's require
    2. If the function is an async, use await import

Note that these rules don't apply to tests. You can always use top-level imports there.

Essential modules

This is a list of the modules that always get loaded during startup:

  • fs
  • path
  • util
  • find-up
  • fs-extra
  • chalk
  • semver
  • deepmerge
  • source-map-support/register

Common errors

Monkey-patching dependencies multiple times

You should avoid monkey-patching whenever possible. But if it's necessary to do so, you should pay extra care when doing it in Buidler or your tests may fail in very hard to debug ways.

When tests are run, Buidler gets initialized multiple times. That may lead to monkey-patching the same multiple times. To avoid this, keep references to the original implementations. In order to do this, you need to get it just once:

let originalImpl; // May be a global

// ...

if (originalImpl === undefined) {
  originalImpl = lib.func;
}

lib.func = function(...args) {
  // Do something;
  return originalImpl.apply(this, args);
};

This isn't normally a problem if you are monkey-patching an object's methods. But it is when monkey-patching a class or its prototype.