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!
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.
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.
In order to develop Truffle, you'll need:
First clone this repository and install NPM dependencies:
$ git clone [email protected]: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.
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
developbranch for new (non-hotfix) development. Pull Requests should be opened againstdevelopin all repositories. See Branching from Develop.
Truffle projects maintain two stable branches:
master, for latest full releases and work targeting a patch releasedevelop, for latest unstable releases and work targeting the next major or minor release.
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
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 [email protected]:ChocolateLover/truffle-artifactor.git
$ git fetch --all
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.
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.
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. 🙇