Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update contribution guidelines #3762

Closed
wants to merge 8 commits into from
Closed

Update contribution guidelines #3762

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
b89800a
Add "are you the Guy?" section
freimair Dec 8, 2019
9964c79
Added "Get started" section
freimair Dec 9, 2019
1ad01ca
Refactored "Pull request rules" section
freimair Dec 9, 2019
aaa3307
Refactored "Further reading"
freimair Dec 9, 2019
092799a
Adjusted header levels
freimair Dec 11, 2019
c2fd63e
Included review comments
freimair Dec 11, 2019
a8a89d9
Include review comments
freimair Feb 27, 2020
6e19734
Merge branch 'master' into update_contribution_guidelines
freimair Feb 27, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 71 additions & 59 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,98 +1,110 @@
# Contributing to Bisq
Read on to find out if taking part in the development of Bisq is for you and how to do it!

Anyone is welcome to contribute to Bisq. This document provides an overview of how we work. If you're looking for somewhere to start contributing, check out [critical bugs](https://bisq.wiki/Critical_Bugs) or see [good first issue](https://github.com/bisq-network/bisq/issues?q=is%3Aopen+is%3Aissue+label%3A"good+first+issue") list.
## Are you "the guy"?

Java God, Bitcoin Native, Marketing Genius, Cypherpunk, Testing Machine, or simply someone who likes the idea of Bisq? Anyone is welcome to contribute! However, Bisq is no classic organization, there is no boss, there is no working hours and there is no classic payment. In short, Bisq is not for everyone.

## Communication Channels
**What is there to work on?** You have to be able to find and work a problem on your own. In general, we do not assign stuff to people, there is no specification to be implemented, there is no given way forward. You yourself have to find, choose and pick something to work on. If you get stuck, we are keen to help, but please do not wait for us to take your hand. Also, you can spend as much (or little) time as you want and when you want to - Bisq still is an open source project.

Most communication about Bisq happens on [Keybase](https://keybase.io).
**Will you get paid?** Well, yes and no. With Bisq, there is no classic funding or investors, so there is no payout of fiat money.
- Yes, you can ask for compensation. If granted, you receive BSQ, a colored bitcoin token. Sell your BSQ and you get your fiat eventually.
- No, because the BSQ market is still bootstrapping. The more correct way to see payment is "compensation". By earning BSQ, you invest in the Bisq project (as you might in a more traditional startup). But make no mistake, the DAO has only been operating for a few months now. Over time, the BSQ market should be able to stay ahead of compensation requests.

Install Keybase and enter "bisq" from the teams tab. This is an "open" team, which means the admins will auto-accept any request to join, and you can get in fast.
**Skills?**
If you want to develop code, we expect you to know your ways around Git and Java. Then comes testing, JavaFX, Gradle, Github, ... If you want to do something else you are good at: marketing, user support, management process optimizations, you are most welcome as well!
If you are good at something Bisq does not even realize it is in need for, well, come on in!

Discussion about code changes happens in GitHub issues and pull requests.
**Carreer?** There is no boss in Bisq - there is only stakeholders. Stakeholders have invested their time, gained some experience with the project and thus, are granted influence on the project accordingly. As soon as you receive your first couple of BSQ, you are a stakeholder too.

Discussion about larger changes to the way Bisq works happens in issues the [bisq-network/proposals](https://github.com/bisq-network/proposals/issues) repository. See https://docs.bisq.network/proposals.html for details.
Start with something small, get yourself familiar with how things are done. Like it? Take on bigger tasks, be it development work, [roles](https://github.com/bisq-network/roles/issues) or other things you believe Bisq is in need for.

All in all, there is no boss, there is no annual raise of salary, there is nobody to take your hand, there is just stakeholders and their passion for the Bisq project.

## Contributor Workflow

All Bisq contributors submit changes via pull requests. The workflow is as follows:

- Fork the repository
- Create a topic branch from the `master` branch
- Commit patches
- Squash redundant or unnecessary commits
- Submit a pull request from your topic branch back to the `master` branch of the main repository
- Make changes to the pull request if reviewers request them and __**request a re-review**__

Pull requests should be focused on a single change. Do not mix, for example, refactorings with a bug fix or implementation of a new feature. This practice makes it easier for fellow contributors to review each pull request on its merits and to give a clear ACK/NACK (see below).
Still here? Nice. You are hired. On to the grind.

## Getting started

## Reviewing Pull Requests
Join Gibhub if you haven't already, fork the Bisq repository, configure your local git ([username](https://help.github.com/articles/setting-your-username-in-git/), [commit signing](https://help.github.com/articles/signing-commits-with-gpg/)), clone your Bisq-fork to disk and do a compile run `./gradlew build`.

Bisq follows the review workflow established by the Bitcoin Core project. The following is adapted from the [Bitcoin Core contributor documentation](https://github.com/bitcoin/bitcoin/blob/master/CONTRIBUTING.md#peer-review):
Now you are ready to roll. Pick something off the [Good First Issue List](https://github.com/bisq-network/bisq/issues?q=is%3Aopen+is%3Aissue+label%3Ais%3Apriority), a [critical bugs](https://bisq.wiki/Critical_Bugs), a [priority task](https://github.com/bisq-network/bisq/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) or pick any other [issue](https://github.com/bisq-network/bisq/issues), do some testing, spot a bug, report it and fix it, maybe there is something in the UI that needs cosmetic work. The possibilities are endless. However, make sure the task you pick is of some importance, otherwise it might cause some inconvenience later on.

Anyone may participate in peer review which is expressed by comments in the pull request. Typically reviewers will review the code for obvious errors, as well as test out the patch set and opine on the technical merits of the patch. Project maintainers take into account the peer review when determining if there is consensus to merge a pull request (remember that discussions may have been spread out over GitHub, mailing list and IRC discussions). The following language is used within pull-request comments:

- `ACK` means "I have tested the code and I agree it should be merged";
- `NACK` means "I disagree this should be merged", and must be accompanied by sound technical justification. NACKs without accompanying reasoning may be disregarded;
- `utACK` means "I have not tested the code, but I have reviewed it and it looks OK, I agree it can be merged";
- `Concept ACK` means "I agree in the general principle of this pull request";
- `Nit` refers to trivial, often non-blocking issues.

Please note that Pull Requests marked `NACK` and/or GitHub's `Change requested` are closed after 30 days if not addressed.
Now that you have picked yourself something to work on, be vocal about it! Claim good first issues, or any issues, by simply leaving a comment saying that this is being worked on, join [Keybase](https://keybase.io/team/bisq). Once there, register your github with keybase, introduce yourself in the channel *#introductions*, get help in *#dev-onboarding* if your setup fights you, use *#dev* to see if the task you picked is a good way forward (you do not have to do that for good first issues though) and join other channels if you want to. Furthermore, check our [event calendar](https://bisq.network/calendar) and tune in on [dev-calls](hhttps://github.com/bisq-network/events/issues?q=Dev-Call), growth-calls and daily standup calls.

Go on and do the actual work. And do not forget to enjoy yourself!

## Compensation

Bisq is not a company, but operates as a _decentralized autonomous organization_ (DAO).

Since our [Q1 2020 update](https://bisq.network/blog/q1-2020-update/) contributions are NOT eligible for compensation unless they are allocated as part of the development budget. Fixes for [critical bugs](https://bisq.wiki/Critical_Bugs) are eligible for compensation when delivered.
In any case please contact the team lead for development (@ripcurlx) upfront if you want to get compensated for your contributions.

For any work that was approved and merged into Bisq's `master` branch, you can [submit a compensation request](https://docs.bisq.network/dao/phase-zero.html#how-to-request-compensation) and earn BSQ (the Bisq DAO native token). Learn more about the Bisq DAO and BSQ [here](https://docs.bisq.network/dao/phase-zero.html).

## Pull request rules

## Style and Coding Conventions
Please honor the list of rules below for your pull request to get merged. Due to very limited resources, we are forced to enforce these quite rigorously.

### Configure Git user name and email metadata
### Honor Git best practice
- Create a topic branch off master
- Commit little, commit often
- Maintain a clean commit history (no merge commits!, use rebase and force-push if necessary)
- Use meaningful commit subjects AND description
- how did stuff work before you touched it, what has been bad back then
- how does the stuff work now and why is that better
- Do so in a well-formed manner (from https://chris.beams.io/posts/git-commit/#seven-rules)
1. Separate subject from body with a blank line
2. Limit the subject line to 50 characters
3. Capitalize the subject line
4. Do not end the subject line with a period
5. Use the imperative mood in the subject line
6. Wrap the body at 72 characters
7. Use the body to explain what and why vs. how

See https://help.github.com/articles/setting-your-username-in-git/ for instructions.
### Respect Bisq's coding style
- The .editorconfig settings in this repository ensure consistent management of whitespace, line endings and more. Most modern editors support it natively or with plugin. See http://editorconfig.org for details. See also bisq-network/style#10.
- Also, please honor the issues in the [bisq-network/style](https://github.com/bisq-network/style/issues) repository
- Do not commit import reorgs or any other non-changes!

### Write well-formed commit messages

From https://chris.beams.io/posts/git-commit/#seven-rules:
### Test your code!
- Create automated tests for your work. JUnit is available. If you are fixing a bug, create a test that demonstrates the bug by failing. Then fix the bug.
- If automated testing is not feasible (we know it can be hard - working on it ...), provide a textual testing procedure (which we can include in our manual testing checklist): setup, prerequisits, steps, expected results
- If that is not possible either, provide some info (numbers, screenshots, testing procedure) on how you tested your stuff
- If all is lost, state why you have not been able to do the above.
freimair marked this conversation as resolved.
Show resolved Hide resolved

1. Separate subject from body with a blank line
2. Limit the subject line to 50 characters
3. Capitalize the subject line
4. Do not end the subject line with a period
5. Use the imperative mood in the subject line
6. Wrap the body at 72 characters
7. Use the body to explain what and why vs. how
### Create a pull request
- Pull requests have to be focused on a single change. Do not mix unrelated stuff.
- Use meaningful title and description
- provide some context, how did stuff work before, how does it work now, why is that better
- are there some introduced/mitigated risks, maybe for backwards compatibility
- how you tested your stuff (so we can do so as well if we feel so)
- and of course, reference issues (if applicable) with the use of [keywords](https://help.github.com/en/github/managing-your-work-on-github/closing-issues-using-keywords)
- Wait for your pull request to be reviewed

See also [bisq-network/style#9](https://github.com/bisq-network/style/issues/9).

### Sign your commits with GPG

See https://github.com/blog/2144-gpg-signature-verification for background and
https://help.github.com/articles/signing-commits-with-gpg/ for instructions.

### Use an editor that supports Editorconfig
### Pull request review prodecure
Bisq follows the review workflow established by the Bitcoin Core project. The following is adapted from the [Bitcoin Core contributor documentation](https://github.com/bitcoin/bitcoin/blob/master/CONTRIBUTING.md#peer-review):
- `ACK` means "I have tested the code and I agree it should be merged";
- `NACK` means "I disagree this should be merged", and must be accompanied by sound technical justification. NACKs without accompanying reasoning may be disregarded;
- `utACK` means "I have not tested the code, but I have reviewed it and it looks OK, I agree it can be merged";
- `Concept ACK` means "I agree in the general principle of this pull request";
- `Nit` refers to trivial, often non-blocking issues.

The [.editorconfig](.editorconfig) settings in this repository ensure consistent management of whitespace, line endings and more. Most modern editors support it natively or with plugin. See http://editorconfig.org for details. See also [bisq-network/style#10](https://github.com/bisq-network/style/issues/10).
In case you receive a NACK and/or `change requested`
- react within 30 days, or else, your pull request will be rejected automatically
- **re-request a review** after adressing a change request (because we almost always only look at "review required" pull request because of resource constraints)

### Keep the git history clean
### Compensation

It's very important to keep the git history clear, light and easily browsable. This means contributors must make sure their pull requests include only meaningful commits (if they are redundant or were added after a review, they should be removed) and _no merge commits_.
Your pull request got merged? great, congrats and thanks for making Bisq more better.
freimair marked this conversation as resolved.
Show resolved Hide resolved

### Additional style guidelines
Since our [Q1 2020 update](https://bisq.network/blog/q1-2020-update/) contributions are NOT eligible for compensation unless they are allocated as part of the development budget. Fixes for [critical bugs](https://bisq.wiki/Critical_Bugs) are eligible for compensation when delivered.
In any case please contact the team lead for development (@ripcurlx) upfront if you want to get compensated for your contributions.

See the issues in the [bisq-network/style](https://github.com/bisq-network/style/issues) repository.
For any work that was approved, merged into Bisq's `master` branch and allocated as part of the development budget, you can [submit a compensation request](https://docs.bisq.network/dao/phase-zero.html#how-to-request-compensation) and earn BSQ (the Bisq DAO native token). Learn more about the Bisq DAO and BSQ [here](https://docs.bisq.network/dao/phase-zero.html).


## See also
## Further reading/other resources worth checking

- tech session on [youtube](https://www.youtube.com/watch?v=ulmUVh3XjRg&list=PLFH5SztL5cYOtcg64PntHlbtLoiO3HAjB)
- dev-calls on [youtube](https://www.youtube.com/watch?v=YnTA3p-5v00&list=PLFH5SztL5cYN1m9v_NvpXxvP7_XIKF3At)
- [contributor checklist](https://docs.bisq.network/contributor-checklist.html)
- [developer docs](docs#readme) including build and dev environment setup instructions