Merge pull request #1924 from cbeams/revise-docs

Revise contributor / developer docs

CONTRIBUTING.md

@@ -1,3 +1,85 @@
-# Bisq Contributor Guidelines
+# Contributing to Bisq
+
+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, see the [good first issue](https://github.com/bisq-network/bisq/issues?q=is%3Aopen+is%3Aissue+label%3A"good+first+issue") list.
+
+
+## Communication Channels
+
+Most communication about Bisq happens in the [Bisq Slack workspace](https://bisq.network/slack-invite).
+
+Discussion about code changes happens in GitHub issues and pull requests.
+
+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.
+
+
+## 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
+ - Submit a pull request from your topic branch back to the `master` branch of the main repository
+
+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 and to give a clear ACK/NACK (see below).
+
+
+## Reviewing Pull Requests
+
+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):
+
+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.
+
+
+## Compensation
+
+Bisq is not a company, but operates as a _decentralized autonomous organization_ (DAO). For any work 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).
+
+
+## Style and Coding Conventions
+
+### Configure Git user name and email metadata
+
+See https://help.github.com/articles/setting-your-username-in-git/ for instructions.
+
+### Write well-formed commit messages
+
+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 also [bisq-network/style#9](https://github.com/bisq-network/style/issues/9).
+
+### Sign your commits with GPG
+
+_Not strictly required, but recommended for those who commit frequently._
+
+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
+
+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).
+
+### Additional style guidelines
+
+See the issues in the [bisq-network/style](https://github.com/bisq-network/style/issues) repository.
+
+
+## See also
+
+ - [contributor checklist](https://docs.bisq.network/contributor-checklist.html)
+ - [developer docs](docs#readme) including build and dev environment setup instructions
 
-See https://github.com/bisq-network/docs/blob/master/CONTRIBUTING.adoc

README.md

@@ -5,48 +5,16 @@
 
 ## What is Bisq?
 
-Bisq is a safe, private and decentralized way to exchange bitcoin for national currencies and other cryptocurrencies. Bisq uses peer-to-peer technology and multi-signature escrow to facilitate trading without the need for a centralized third party exchange. Bisq is non-custodial (never holds your funds), and incorporates a human arbitration system to resolve disputes.
+Bisq is a safe, private and decentralized way to exchange bitcoin for national currencies and other digital assets. Bisq uses peer-to-peer networking and multi-signature escrow to facilitate trading without a third party. Bisq is non-custodial and incorporates a human arbitration system to resolve disputes.
 
-For more information, see https://bisq.network/intro and for step-by-step getting started instructions, see https://bisq.network/get-started.
+To learn more, see the doc and video at https://bisq.network/intro.
 
 
-## Building Bisq
+## Get started using Bisq
 
-You will need OpenJDK [JDK 10](https://jdk.java.net/10/) installed to complete the following instructions.
+Follow the step-by-step instructions at https://bisq.network/get-started.
 
-1. Clone the Bisq source code and cd into `bisq`
 
-        git clone https://github.com/bisq-network/bisq
-        cd bisq
-
-2. Build Bisq
-
-    You do _not_ need to install Gradle to complete the following command. The `gradlew` shell script will install it for you if necessary.
-
-        ./gradlew build
-
-
-## Running Bisq
-
-With the above build complete, the Bisq executable jar is now available in the `desktop/build/libs/` directory. Run it as follows, replacing `{version}` with the actual version found in the filename:
-
-    java -jar desktop/build/libs/desktop-{version}-all.jar
-
-
-## Importing Bisq into Intellij IDEA
-
-_The following instructions have been tested on IDEA 2018.2_
-
- 1. Open IDEA
- 1. Go to `Help->Edit Custom Properties...`, add a line to the file that reads `idea.max.intellisense.filesize=12500` (to handle Bisq's very large generated `PB.java` Protobuf source file)
- 1. Go to `Preferences->Plugins`. Search for and install the _Lombok_ plugin. When prompted, do not restart IDEA.
- 1. Go to `Preferences->Build, Execution, Deployment->Compiler->Annotation Processors` and check the `Enable annotation processing` option (to enable processing of Lombok annotations)
- 1. Restart IDEA
- 1. Go to `Import Project`, select the `settings.gradle` file and click `Open`
- 1. In the `Import Project from Gradle` screen, check the `Use auto-import` option and click `OK`
- 1. When prompted whether to overwrite the existing `.idea` directory, click `Yes`
- 1. In the `Project` tool window, right click on the root-level `.idea` folder, select `Git->Revert...` and click OK in the dialog that appears (to restore source-controlled `.idea` configuration files that get overwritten during project import)
- 1. Go to `Build->Build Project`. Everything should build cleanly. You should be able to run tests, run `main` methods in any component, etc.
-
-> TIP: If you encounter compilation errors related to the `io.bisq.generated.protobuffer.PB` class, it is probably because you didn't run the full Gradle build above. You need to run the `generateProto` task in the `common` project. You can do this via the Gradle tool window in IDEA, or you can do it the command line with `cd common; ./gradlew generateProto`. Once you've done that, run `Build->Build Project` again and you should have no errors.
+## Contribute to Bisq
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the [developer docs](docs#readme).