This document provides an overview of how you can contribute to 3Box. We're excited to have you building with us. 🎉
This section contains useful links to get you started building.
To view our active work, view the 3Box project board or download the Zenhub browser extension.
Join the 3Box Community so you can connect with other developers and the core team on our Discord Chat.
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.
We use Github Issues for individual items of work, such as issues, tasks, and stories. Here's an example.
We use Github Labels to label issues. Using labels helps keep issue lists and project boards skimmable.
Development
Tech Research
Front End
Ops
Design
Content & Community
Customer Development
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.
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)
- Determine what kind of release you are creating:
- Look at all the changes that will be applied with
git diff develop master
andgit log
. If you need help understanding the impact of other contributors' work, ping them. - 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.
- Look at all the changes that will be applied with
- Create a release branch off
develop
namedrelease/v<version-number>
- Prepare the relase:
- Add release notes to
RELEASE-NOTES.md
. Make sure it includes all changes that are being applied (not just your latest work) - 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.
- Add release notes to
- Push the branch and open a PR against
master
- Let the dev team know, and get the PR approved, then merge it
- 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.- 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.
- If anything goes wrong, rollback by going into CI, finding the previous working build of
master
and rerunning the job. - 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.
- 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"
- Push the tag with
git push --tags <tag-name>
- Apply the release to the develop branch:
- Check out
develop
git merge master
git push
- Check out