Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time

How to Contribute 🛠️

This document provides an overview of how you can contribute to 3Box. We're excited to have you building with us. 🎉

Getting Started

This section contains useful links to get you started building.

View the Project Board

To view our active work, view the 3Box project board or download the Zenhub browser extension.

Join the Chat

Join the 3Box Community so you can connect with other developers and the core team on our Discord Chat.

Report an Issue or Bug

Some guidelines for reporting bugs:

  • Make sure that your issue is caused by the corresponding 3box library and not your application code.
  • Create a simple and minimal test case that demonstrates the bug.
  • Search the issues to see if the bug has already been reported. If it has, add any additional details in the comments.
  • Write a descriptive and specific title.
  • Include browser, OS, 3box library version and any other details specific to the environment.
  • Check whether the bug can be reproduced in other environments (ie. other browsers).

Click one of the links below to create a new issue in the appropriate repo:

Before submitting your changes run npm run lint to find any formatting issues that don't adhere to the original codebase.


This section contains information about the various tools used by our project.

Issues and Stories

We use Github Issues for individual items of work, such as issues, tasks, and stories. Here's an example.

Issue Labels and Tags

We use Github Labels to label issues. Using labels helps keep issue lists and project boards skimmable.


Tech Research

Front End



Content & Community

Customer Development

Project Management

For our kanban or organization board we use Zenhub. To view our active work, you can view the 3Box project board or you can download the Zenhub browser extension to have the project board injected more natively into Github on Chrome or Firefox.

Best Practices

Click here for repo best practices.

  • Dont leave things in done if you are on the core team, since you have the power to take it to closed!

  • Leave closing comments on issues closed but left incomplete or undone, so the community can follow along

  • Submit issues and PRs in the appropriate 3Box repo (we use this one as a project hub)

Project Owners

Creating a release

  1. Determine what kind of release you are creating:
    1. Look at all the changes that will be applied with git diff develop master and git log. If you need help understanding the impact of other contributors' work, ping them.
    2. Version increment according to semver:
      • MAJOR: when you make incompatible API changes
      • MINOR: when you add functionality in a backwards compatible manner, and
      • PATCH: when you make backwards compatible bug fixes.
  2. Create a release branch off develop named release/v<version-number>
  3. Prepare the relase:
    1. Add release notes to Make sure it includes all changes that are being applied (not just your latest work)
    2. Log the new version number (usually in package.json). If it's an npm package, regenerate the package lockfile to also apply the version change there.
  4. Push the branch and open a PR against master
  5. Let the dev team know, and get the PR approved, then merge it
  6. If the project includes a deployment step, merging into master will deploy against production automatically, and has to be tested again. Otherwise, skip this step.
    1. Once the project is deployed (watch progress through CI), test it out (for example, by using the example server against production) to make sure everything looks good.
    2. If anything goes wrong, rollback by going into CI, finding the previous working build of master and rerunning the job.
    3. This is a temporary fix that gives you time to analyze what went wrong - if it's related to the release, you need to remove the code from the master branch with a revert.
  7. If it all looks good, pull the master branch locally and create a version tag with git tag -a v<version-number> -m "release v<version-number"
  8. Push the tag with git push --tags <tag-name>
  9. Apply the release to the develop branch:
    1. Check out develop
    2. git merge master
    3. git push