# Contributing Guide

We welcome you to submit pull requests to the [pm-js Github repo](https://github.com/gnosis/pm-js), and we will do our best to make sure they are reviewed. If your pull request isn't adjusted and merged, at least the idea and use case scenario will be taken into consideration. That said, if something is a significant time investment, consider describing the change in an issue first before you take the plunge.

The rest of this article will detail getting started with setting up a local development copy of pm-js.

## Installation

First use Git to clone the [repo](https://github.com/gnosis/pm-js).

Run `npm install` to install dependencies.

You will also need a Web3 provider to develop against. If you don't have one, try [Ganache](http://truffleframework.com/ganache/).

## Development

Make sure you have a node connected to a chain with a JSONRPC interface exposed on localhost:8545.

Before you begin, you will want to have the contracts deployed on the chain you plan to use. You can deploy contracts through the RPC interface on localhost:8545 with

```
npm run migrate
```

The build process using Truffle will insert the chain locations in a `networks` key on the contract build artifacts.

### Editing Source

The ES6 source can be found in the `src` folder. Be sure to edit the JavaScript files found in `src` and *not* the ones found in `dist`. Those files are built from the ES6 source in `src`.

### Building

You can run `npm run nodebuild` to build the library for Node.js use. This will transpile the ESM modules in `src` to corresponding CJS Node.js modules in `dist`.

You can also run `npm run webbuild` to build the library targeting the web. Note that this will compile in all network information present in the build artifacts, including temporary network information generated by Ganache-cli during migrations. You may use `npm run netreset` beforehand to remove unofficial network info and reset to official deployed locations if desired.

### Running the dev server

Run `npm run dev` to run the dev server and serve the examples. This will spin up Ganache CLI in the background on [http://localhost:8545](http://localhost:8545) and migrate the contracts on that Ganache instance. The JS library source will be continuously recompiled. Examples will be available on [http://localhost:8080](http://localhost:8080). Don't forget to refresh the page after you change the source.

### Running the tests

Run `npm test` to run test suite. This should run without the need of an RPC provider running on localhost:8545. If you already have such a provider running and wish to run the test suite without automatically spinning up [Ganache-cli](https://github.com/trufflesuite/ganache-cli) and causing a chain migration, use `npm run test-manual`.

You may also provide mocha options through the `MOCHA_OPTS` environment variable, e.g. `MOCHA_OPTS='-g estimate' npm test`.

### Building these docs

The documentation generator requires Python to be present on your computer. Install the required Python packages into your environment via

```
pip install -r docs/requirements.txt
```

Afterwards, run `npm run doc` to build and open a local build of the documentation in your browser.

You can also spin up a documentation build watcher with `npm run docwatch`. The documentation will be served from [port 8000](http://localhost:8000).

## Pull Request Etiquette

As long as we like your pull request, we promise we won't nitpick on little things. That said, we would appreciate it if you observe the following:

* Make sure the changeset for your PR is comprehensible. Basically, don't commit `dist/gnosis-pm-js` if you happen to rebuild it. We will do that every release.
* Please write tests for new features, and consider adding regression tests for fixes.
* Make each commit/PR about one thing if you can.
