Skip to content

Latest commit

 

History

History
180 lines (114 loc) · 6.07 KB

CONTRIBUTING.md

File metadata and controls

180 lines (114 loc) · 6.07 KB
Raw

Contributing to Truffle

Thanks for taking the time to help out and improve Truffle! 🎉

The following is a set of guidelines for Truffle contributions and may change over time. Feel free to suggest improvements to this document in a pull request!

Contents

How Can I Contribute?

Development

Additional Notes

How Can I Contribute?

All contributions are welcome!

If you run into an issue, the first step is to reach out in our Gitter channel, in case others have run into the problem or know how to help.

To report a problem or to suggest a new feature, open a GitHub Issue. This will help the Truffle maintainers become aware of the problem and prioritize a fix.

For code contributions, for either new features or bug fixes, see Development.

If you're looking to make a substantial change, you may want to reach out first to give us a heads up.

Development

Overview

Truffle is organized as a collection of repositories, each with their own NPM package.

This repository (trufflesuite/truffle) is a distribution package and only contains logic to build Truffle for release.

The main development repository is trufflesuite/truffle-core, containing the command-line interface (CLI) and some core logic. Other Truffle repositories are included via dependencies specified in truffle-core's package.json

Truffle uses meta to help manage changes across multiple repositories.

Development Requirements

In order to develop Truffle, you'll need:

Getting Started

First clone this repository and install NPM dependencies:

$ git clone git@github.com:trufflesuite/truffle.git
$ cd truffle
$ npm install

Use meta to obtain the rest of the Truffle repositories:

$ meta git update
$ meta npm install

Your local Truffle copy will now contain a dependencies/ directory, with all the other Truffle repos located there.

You'll want to link these repositories to each other, so that changes you make in one package are used by the others:

$ meta npm symlink

(For instance, if you make a change to truffle-migrate, it will be used by truffle-core)

Note for Windows Users: Default permissions prevent users from making symbolic links. You may need to run your shell as an administrator, or change your policy settings. See this Superuser StackExchange answer for more information.

Forks, Branches, and Pull Requests

Community contributions to Truffle require that you first fork the repositor(y|ies) you are modifying. After your modifications, push changes to your fork(s) and submit a pull request upstream to trufflesuite's fork(s).

See GitHub documentation about Collaborating with issues and pull requests for more information.

❗ Note: Truffle development uses a long-lived develop branch for new (non-hotfix) development. Pull Requests should be opened against develop in all repositories. See Branching from Develop.

Branching Model

Truffle projects maintain two stable branches:

  • master, for latest full releases and work targeting a patch release
  • develop, for latest unstable releases and work targeting the next major or minor release.

Branching From Develop

Check-out develop in all Truffle repositories with the following meta command:

$ meta pkgs checkout truffle:develop

If you've used develop before, you may need to pull changes:

$ meta git pull

If dependencies have changed, you may need to install and re-link dependencies:

$ meta npm install
$ meta npm symlink

Tracking Forks Locally

For each forked repository you are making modifications to (e.g. GitHub username @ChocolateLover modifying truffle-artifactor):

$ cd dependencies/truffle-artifactor
$ git remote add ChocolateLover git@github.com:ChocolateLover/truffle-artifactor.git
$ git fetch --all

Working on a Branch

Use a branch for your modifications, tracking it on your fork:

$ git checkout -b sweet-feature
$ git push -u ChocolateLover sweet-feature

Then, make changes and commit as usual.

Changes Spanning Multiple Repos

For changes spanning multiple repositories, it may help to use the same branch name for each.

If you need to switch between branches, you can use the meta pkgs plugin (readme) to checkout en-masse:

$ meta pkgs checkout truffle:develop truffle:ChocolateLover/sweet-feature --greedy

This will checkout sweet-feature from @ChocolateLover's fork for all projects, falling back to develop.

Additional Notes

Join the chat in our Gitter channel. If anything about this process is unclear, or for helpful feedback of any kind, we'd love to hear from you!

Thanks again for all your support, encouragement, and effort! Truffle would not be possible without contributors like you. 🙇