-
Notifications
You must be signed in to change notification settings - Fork 173
Developer resource page
Developers
OpenBazaar is an open source project. We love contributions. We would like to work more bazaar-style and encourage external authors. Thanks for your interest in contributing. You're amazing!
OpenBazaar has three code repositories.
-
OpenBazaar-Server. This repository manages the back end: The p2p networking; creation, signing and verification of the Ricardian contracts; and management of multisig Bitcoin keys. The code is mostly Python.
-
OpenBazaar-Client. This repository manages the front end and is the reference client for the project. It uses both a websocket and REST API to talk to the server. The client is an Electron app, built on Backbone. The code is JavaScript, HTML, and CSS.
-
OpenBazaar-Installer. This repository manages the installation of the other two repositories. It will support installation on Windows, OSX, and the majority of Linux distributions.
OpenBazaar server and client talk to each other using both REST and websocket APIs.
REST API documentation is available here. Websocket documentation coming soon.
-
Join our community Slack to ask questions and help coordinate development.
-
View our Waffle.io page to see open issues on the client side.
-
View open Github issues to see how you can help with the server side.
-
Read the guidelines below to understand how to properly contribute to development.
This document outlines some guidelines so that your contributions can be included in the codebase.
To contribute, follow these steps:
-
Fork the GitHub repo.
-
For the server:
- git clone [email protected]:your-username/OpenBazaar-Server.git
-
For the client:
- git clone [email protected]:your-username/OpenBazaar-Client.git
-
Configure remotes so that you can merge back from upstream.
-
For the server:
- git remote add upstream https://github.com/OpenBazaar/OpenBazaar-Server.git
-
For the client:
- git remote add upstream https://github.com/OpenBazaar/OpenBazaar-Client.git
-
Find an issue that you want to fix in the server or client repositories.
-
Create a new branch in your clone:
-
git checkout master git checkout -b my_feature
-
Write tests for your fix.
-
Implement your fix.
-
Make sure the build passes:
-
make
-
Push your new branch with your changes to your fork:
-
git push origin my_feature
-
Submit a pull request to master.
Be careful:
-
Do not work on the main OpenBazaar GitHub repos directly, even if you are a collaborator.
-
Do not work directly on your local branches.
You should never need to touch the master branch on your local machine or on your personal GitHub repo directly. When you want to update them, simply pull from upstream and push to your origin.
There are a few ways to find something to do on the project:
-
You want to implement a feature we're already planning. Great! We don't yet have a detailed roadmap, but we're working on having one on our wiki. For now, visit us in our Slack so that we can tell you about our plans. You may also find some discussion on the feature/plan in one of the issues. Mention that you'll be working on it (or assign it to yourself if you're a collaborator). If someone else is working on it, please collaborate with them; they may need your help and we don't want to do the same work twice. If you cannot find any such issue, please open a new one and publish your thoughts. If the issue is heavy on the technical side, do not forget to include any useful links (RFCs, Wikipedia entries, StackOverflow posts, mailing list threads – you get the idea).
-
You have an idea about a new feature. Please go ahead and implement it! It may well be something we haven't thought about – thanks for enriching our codebase. Nevertheless, before embarking on your project, please talk to us on Slack. This is important, because we may already have plans for a feature of this kind. In that case, the plans may detail how we envision to build your idea and you may want to follow these plans or at least discuss them with us.
-
You have found a bug: Reporting bugs is extremely valuable to us. Please proceed directly to the issues page and check if someone is experiencing the same problem as you. If not, open a new issue including:
-
Your hardware and software architecture (e.g. "I am using OpenBazaar version 1.0.2 on Debian wheezy 64-bit over Python 2.7.6"). If you are on a Unix- flavored system, the following commands may help you:
-
python --version uname -ar
-
How you installed our project. Did you git-clone the nightly, did you attempt to install it via the debian package, did you do a hybrid setup? What’s the current commit hash?
-
What error you are observing. Does the system crash with an exception, (which one?), does it hang (please provide a screenshot if relevant), does it do something quirky?
-
A copy of the project logs. These can be found in the /OpenBazaar/ folder. Logs are extremely useful. Please make a gist with your log and provide a link in your report. WARNING: This log may contain sensitive information from your software.
-
-
You have a found a bug you can fix or some other problem in the code: Maybe the project is not yet working on your favourite hardware or software architecture; maybe a bug in our codebase is causing too much trouble; perhaps you'd like to see the project uphold to higher standards before you use it. We definitely want your input on this! If you feel your programming skills and your understanding of the project is sufficient, we will be glad if you helped us. Just go to the open issues page, pick an issue that you think is worthy, and start working on it. Leave a comment indicating your intention or assign the issue to yourself. Double-check that no one else is doing the same work; if they are, please collaborate! If the issue is new and you manage to fix it, then please submit the issue and the patch in the form of a Pull Request. See the Workflow and the Reviewing Pull Requests sections for details on how to go about it. Once again, thank you for contributing!
-
Look at the code and see if you can refactor something. Look for broken windows. pylint can sometimes be a good guide. Running pylint:
-
pylint node --rcfile=.pylintrc
-
Please be bold in your pull requests. If you have a big idea, you're very welcome to create an issue and bring it up for discussion.
OpenBazaar is security-related software. We make heavy use of cryptography and the blockchain. We employ Ricardian contracts, 2-of-3 multisig, and other features that are of critical importance to the network.
We take our users' security and anonymity seriously, and it is our first priority to protect them.
As such, we require certain code quality from contributors. Auditing of software is much more efficient when the code is clear, simple, modular, and orthogonal. Therefore, we may be stricter in our pull request reviews than you may be used to from other software projects. This is intentional.
This does not mean we don't appreciate your patches. On the contrary, we appreciate your work enough to devote time to review it in depth and ensure it is of good quality when it gets merged.
If you make a pull request with your change, we promise to review it as soon as possible. Hopefully we will review it within a few days – we try to be responsive.
Reviewing means you'll either get a comment with a request to change something, or we'll merge your pull request. If we request a change and you make it, we'll review you again.
Pull requests are reviewed by our peers, just like you. You can also review pending pull requests by others too! Just go to the list of open pull requests, pick one you want to see merged, and see if the code looks good. If you see some issue, leave a comment on the particular line of code, or on the pull request itself. If everything looks good to you, leave a comment indicating that it's ready to be merged. You can say "LGTM" for "Looks Good To Me". If you're a collaborator, you can also merge pull requests directly in this case.
Try to make one pull request per issue. If you want to make two changes, make two different branches from develop and pull request. If multiple changes depend on each other, then you should still make a different branch for each change – but base the dependent branch on the branch it depends on instead of develop. After you make your changes, you should make two different pull requests. First, make a pull request from the base branch (that the other branch was based on). Finally, make a pull request for the dependent branch. Write a comment on your pull request of the dependent branch saying it depends on a previous pull request by mentioning the previous pull request. We'll then review them in order.
If a pull request fixes an issue, mention the issue it fixes in your pull request description or in one of your commit messages, such as "Fix #007". When the pull request is merged, you can close the issue too.
Please don't merge your own pull requests! Peer review exists to ensure our software is of good quality. Even the most experienced programmers make mistakes. It's important that the code is seen by at least the person who wrote it and someone else.
Also, never push directly to the upstream repo, only your fork. All code changes must go through pull requests.
Again, please note that we merge to master for now but after version 1.0 is released will merge to develop, not directly to master. The master branch is reserved for stable releases, and we update it on every release cycle, or for important security fixes or other critical bug fixes.
develop will be our working branch. Anything that is merged into develop will be deployed to production within the next release cycle.
If you want to show your work to others, but your pull request is not yet ready for merging, please prefix its title with[WIP], indicating that it is a work in progress. We won't merge work-in-progress pull requests until the indicator is removed from the title.
We try to ensure the quality of the code we merge is decent. Here are some things we look for:
-
The change fixes a real problem, introduces a new feature, or usefully refactors existing code. We look for the GitHub issue it corresponds to to see that it really does fix the problem. If it's a new feature, we make sure it follows our overall vision for OpenBazaar.
-
The change fixes one problem and not multiple problems. Or that it introduces one feature, not multiple. If the pull request can be split up to multiple ones, we'll ask you to do so. If it's one big feature, you may want to split it up into several pull requests introducing it partially so that reviews can be expedited.
-
The change is architecturally sound. We want to keep our code organized based on correct software design principles and maintain modularity, extensibility, and orthogonality. We also value simplicity and elegance and want to make sure we don't overabstract.
-
The change is tested. We are starting to include tests for our code changes, especially in back-end code. While most of our code is currently untested, we may ask you to write tests for new code. We do this so that new code is tested and eventually unit tests can be written for the old code as well. That way, we don't decrease our coverage and we don't introduce new but untested code. Ideally, you should make sure all use cases are covered. This doesn't include just all lines of code, but also all the categories of use cases you can think of. This is not a strict policy yet, but in the future we may not merge code that doesn't include unit tests. If you make a bug fix, we suggest a regression test. We recommend that you follow test-driven development principles and write tests before you implement.
-
The tests pass. This includes tests that were not written for the specific change – all tests must pass. We do not merge a failing build. You can run all tests using make. We use travis to automatically run tests on every pull request and on every merge. You should also enable it on your fork so that tests run after each push.
-
Screenshots are included. We currently don't automatically test front-end code. However, we ask you to provide a screenshot with any front-end change you make. This includes HTML, CSS, and JS changes. If you're fixing a front-end bug, please upload a screenshot of the buggy situation as well as the fixed situation. If it's a new feature, include a screenshot of how it looks at every state. These screenshots can be included in a pull request comment.
-
Coding style guidelines are followed. We're pretty strict about coding style and will not merge until you fix formatting issues. This ensures consistency across our codebase. We follow pep8 in our Python code, and JSHint for our Javascript. Our build includes tests for style conformance so that you have some guidance about formatting.
-
Your commits are clean. If you have commits that you've used for debugging purposes and for style fixes, these must be interactively rebased and potentially squashed. We will ask you to do that before we're ready to merge you. Your commit messages should also be descriptive.
-
Your branch is rebased onto develop. If changes by others have been merged into develop since your pull request, you must rebase your branch onto develop before we can merge your branch. We have many external contributors. To achieve a cleaner history, we prefer rebasing over merging.
-
You have sufficiently documented your code. If a lot of code is affected by your pull request, make sure it is commented; follow your judgement on what needs explaining and make sure the code and the comments match. Please include docstrings in all of the important new functions or classes.
-
You have a nice pull request. While we do not strictly require it, we urge you to accompany your pull request with a comprehensive description:
-
what does it change or fix (Changelog)
-
why did you do it (Motivation)
-
how can we use the new features (Usage guide)
-
how should we further develop it (Roadmap)
-
etc
-
-
The description does neither have to be lengthy nor contain all of the above; it just has to be structured and clear. Consider your pull request description as documenting the evolution of our codebase; anyone who seeks to find if a feature has been implemented or a bug has been fixed should be able to read the pull request and feel certain that this is the case without having to resort to the code.
If you contribute often and become a trusted member of our team, we may give you commit access so that you can assign issues to yourself, have issues assigned to you, or merge pull requests by others. Please follow the guidelines above.
Please note that because OpenBazaar is security-related software, we are reluctant to give contributor access to too wide a range of committers. Don't take it personally – this doesn't mean we don't appreciate your efforts, just that we're especially diligent when it comes to security.
We're an open source project. We release our code under the MIT license. By contributing to the project, you are agreeing to make your modifications available to the world for ever, even if you change your mind later.
See the full license for more information.
We maintain a blog. Check back often for important release and feature announcements.
We don't often use a development mailing list like most open source projects. The best way to reach the development team is through Slack.
We also have an OpenBazaar twitter account and an active OpenBazaar subreddit which is an excellent place to ask questions and get answers. We encourage you to post there and, if you're a more experienced contributor, to answer any questions users may have.