diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index e8c3e6c67d..0000000000 --- a/docs/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# Docs - -- [idea-import.md](idea-import.md): Import sources into IntelliJ IDEA (Bisq) -- haveno mockups.pdf: early UI mockup made by Woodser, to be used for inspiration. \ No newline at end of file diff --git a/docs/build.md b/docs/build.md deleted file mode 100644 index 499f06142b..0000000000 --- a/docs/build.md +++ /dev/null @@ -1,74 +0,0 @@ -## Building Bisq - -1. **Install Git LFS** - - Bisq uses Git LFS (Large File Storage) to track certain large binary files. Follow the instructions at https://git-lfs.github.com to install it, then run the following to command to verify the installation: - - ```sh - git lfs version - ``` - - You should see the version of Git LFS you installed, for example: - - ```sh - git-lfs/2.10.0 (GitHub; darwin amd64; go 1.13.6) - ``` - -2. **Clone Bisq** - - ```sh - git clone https://github.com/bisq-network/bisq - cd bisq - ``` - -3. **Pull LFS data** - - ```sh - git lfs pull - ``` - -4. **Build Bisq** - - On macOS and Linux, execute: - ```sh - ./gradlew build - ``` - - On Windows: - ```cmd - gradlew.bat build - ``` - - If you prefer to skip tests to speed up the building process, just append _-x test_ to the previous commands. - -### Important notes - -1. You do _not_ need to install Gradle to build Bisq. The `gradlew` shell script will install it for you, if necessary. - -2. Bisq currently works with JDK 11 only. JDK 12 and above are not supported. You can find out which - version you have with: - - ```sh - javac -version - ``` - -If you do not have JDK 11 installed, check out scripts in the [scripts](../scripts) directory or download it manually from https://jdk.java.net/archive/. - -## Running Bisq - -Once Bisq is installed, its executables will be available in the root project directory. Run **Bisq Desktop** as follows: - -On macOS and Linux: -```sh -./bisq-desktop -``` - -On Windows: -```cmd -bisq-desktop.bat -``` - -## See also - - - [Importing Bisq into IntelliJ IDEA](./idea-import.md) - - [Bisq development environment setup guide](./dev-setup.md) diff --git a/docs/dev-setup.md b/docs/dev-setup.md deleted file mode 100644 index 82e35aa868..0000000000 --- a/docs/dev-setup.md +++ /dev/null @@ -1,97 +0,0 @@ -# Bisq dev setup guide - -This guide describes how to set up a complete Bisq development environment running against a local Bitcoin regtest network. You'll run your own Bisq seed node, arbitration and trading instances in order to allow for end-to-end development and testing. - - -## Prerequisites - -Follow the instructions in [build.md](build.md) to build Bisq from source, and it is also recommended to follow the instructions in [idea-import.md](idea-import.md) to be able to run everything from within IntelliJ IDEA. Please also read and follow the instructions in [CONTRIBUTING.md](../CONTRIBUTING.md) prior to submitting any pull requests. - - -## Overview - -When developing Bisq, you usually want to use Bitcoin in **regtest** mode and do all networking on **localhost** instead of using the Tor network. Typically, you'll want an environment set up with the following components: - - - Bitcoin Core or bitcoind in regtest mode - - A local Bisq seed node - - A local Bisq arbitrator & mediator instance - - 2 local Bisq trading instances (BTC buyer and BTC seller for executing a trade) - -You'll set up each of these in the steps that follow. - - -## Run Bitcoin Core (or bitcoind) in regtest mode - -The regtest mode operates a local Bitcoin network on your computer. This environment is ideally suited for testing because you are able to create blocks on demand (no need to wait for confirmations) and you don't need to download the blockchain. By creating blocks you act like a miner and you can generate new Bitcoin. - -You can find more information about the Bitcoin regtest mode [here](https://bitcoin.org/en/developer-examples#regtest-mode). - -Navigate to the [bitcoin.conf](https://en.bitcoin.it/wiki/Running_Bitcoin#Bitcoin.conf_Configuration_File) file and set `regtest=1` and `peerbloomfilters=1`, or add `-regtest -peerbloomfilters=1` as a program arguments when starting Bitcoin Core. - -At first startup you need to create 101 blocks using the command `generatetoaddress 101 address`* from the terminal inside Bitcoin Core, where `address` value could be obtained with the command `getnewaddress`. 101 blocks are required because of the coin maturity (100 blocks) so you need one more to have at least 50 BTC available for spending. - -Example: - - generatetoaddress 101 bcrt1qhqn0t94uc269szakr4ez0zh7erdd6tlm4pv6mg - -Later you can create new blocks with `generatetoaddress 1 address`*. - -*If you are using Bitcoin Core v.0.18 or less, use instead `generate 1`. - -## Understand Bisq P2P network options - -For the local P2P network we prefer to use `localhost`, not the Tor network as it is much faster. But if needed you can combine any of the following combinations of Bitcoin network mode and P2P network mode: - - - localhost + regtest - - localhost + testnet - - localhost + mainnet - - Tor + regtest - - Tor + testnet - - Tor + mainnet - - -## Understand Bisq program arguments - -There are several program arguments required to run in development mode. - -Here is an overview: - - - `--baseCurrencyNetwork`: The BTC network to use. Possible values are: `BTC_REGTEST`, `BTC_TESTNET`, `BTC_MAINNET` (default) - - `--useLocalhostForP2P`: Uses localhost instead of Tor for Bisq P2P network - - `--nodePort`: Port number for localhost mode. For seed nodes there is a convention with the last digit is marking the network type and there is a list of hard coded seed nodes addresses (see: `DefaultSeedNodeAddresses.java`). For regtest: 2002 and 3002. For testnet 2001, 3001 and 4001 and for mainnet: 2000, 3000 and 4000. For normal nodes the port can be chosen freely. - - `--useDevPrivilegeKeys`: Important for dev testing to allow the developer key for arbitration registration - - `--appName`: Custom application name which is used for the data directory. It is important to separate your nodes to not interfere. If not set, it uses the default `Bisq` directory. - - -## Run Bisq seednode - -For localhost/regtest mode run the `SeedNodeMain` class or `./bisq-seednode` script in the root project dir with following program arguments: - - --baseCurrencyNetwork=BTC_REGTEST --useLocalhostForP2P=true --useDevPrivilegeKeys=true --nodePort=2002 --appName=bisq-BTC_REGTEST_Seed_2002 - - -### Run Bisq arbitrator/mediator instance - -For localhost/regtest mode run the `BisqAppMain` class or `./bisq-desktop` script in the root project dir with following program arguments: - - --baseCurrencyNetwork=BTC_REGTEST --useLocalhostForP2P=true --useDevPrivilegeKeys=true --nodePort=4444 --appName=bisq-BTC_REGTEST_arbitrator - -Once it has started up go to `Account` and click `CMD +n`. This will open a new tab for `Arbitration registration`. Select the tab and you will see a popup with a pre-filled private key. That is the developer private key (which is only valid if `--useDevPrivilegeKeys` is set) which allows you to register a new arbitrator. Follow the next screen and complete registration. -Next you have to register a mediator as well. Click `CMD + d`. This will open a new tab for `Mediator registration`. Follow the same steps as for the arbitrator registration before. Registration of legacy arbitrators was done with `CMD +n`. It is not needed anymore so we refer with the term arbitrator to the new arbitrator (or refund agent). - -_Note: You need only register once but if you have shut down all nodes (including seed node) you need to start up the arbitrator again after you start the seed node so the arbitrator re-publishes his data to the P2P network. After it has started up you can close it again. You cannot trade without having an arbitrator available._ - - -### Run two Bisq trade instances - -For localhost/regtest mode run the `BisqAppMain` class or `./bisq-desktop` script in the root project dir with following program arguments: - - --baseCurrencyNetwork=BTC_REGTEST --useLocalhostForP2P=true --useDevPrivilegeKeys=true --nodePort=5555 --appName=bisq-BTC_REGTEST_Alice - -and - - --baseCurrencyNetwork=BTC_REGTEST --useLocalhostForP2P=true --useDevPrivilegeKeys=true --nodePort=6666 --appName=bisq-BTC_REGTEST_Bob - -At this point you can now perform trades between Alice and Bob using your local regtest environment and test from both the buyer's and seller's perspective. You can also open disputes with `cmd+o` and see how the arbitration system works (run the arbitrator in that case as well). - -_Remember to generate a new block in the Bitcoin Core console after taking an offer using the command `generatetoaddress 1 address` to trigger a block confirmation._ diff --git a/docs/edit_configurations.png b/docs/edit_configurations.png deleted file mode 100644 index 993128335d..0000000000 Binary files a/docs/edit_configurations.png and /dev/null differ diff --git a/docs/release-process.md b/docs/release-process.md deleted file mode 100644 index 77c5cb3300..0000000000 --- a/docs/release-process.md +++ /dev/null @@ -1,242 +0,0 @@ -# Release Process - -* Update translations [translation-process.md](translation-process.md#synchronising-translations). -* Update data stores [data-stores.md](data-stores.md#update-stores). -* Update bitcoinj checkpoint [bitcoinj-checkpoint](bitcoinj-checkpoint.md#update-checkpoint). -* Write release notes (see below). -* Webpage (Prepare PR) - * Update version number in: - * [_config.yml](https://github.com/bisq-network/bisq-website/blob/master/_config.yml) - - * Update currency list - in [market_currency_selector.html](https://github.com/bisq-network/bisq-website/blob/master/_includes/market_currency_selector.html) ( - use [MarketsPrintTool](https://github.com/bisq-network/bisq/blob/master/desktop/src/test/java/bisq/desktop/MarketsPrintTool.java) - to create HTML content). - -### Bisq maintainers, suggestion for writing release notes - -To be able to create release notes before you make the final release tag, you can temporarily create a local tag and -remove it afterwards again. - - git tag v(new version, e.g. 0.9.4) #create tag - git tag -d v(new version, e.g. 0.9.4) #delete tag - -Write release notes. git shortlog helps a lot, for example: - - git shortlog --no-merges v(current version, e.g. 0.9.3)..v(new version, e.g. 0.9.4) - -Generate list of authors: - - git log --format='- %aN' v(current version, e.g. 0.9.3)..v(new version, e.g. 0.9.4) | sort -fiu - -1. Prepare the release notes with major changes from user perspective. -2. Prepare a short version of the release notes for the in-app update popup - -### Basic preparations - -For releasing a new Bisq version you'll need Linux, Windows and macOS. You can use a virtualization solution -like [VirtualBox](https://www.virtualbox.org/wiki/Downloads) for this purpose. - -#### VirtualBox recommended configuration - -Although performance of VMs might vary based on your hardware configuration following setup works pretty well on macOS. - -Use VirtualBox > 6.1 with following configuration: - -* System > Motherboard > Base Memory: 4096 MB -* System > Processor > Processor(s): 2 CPUs -* System > Processor > Execution Cap: 90% -* Display > Screen > Video Memory: 128 MB -* Display > Screen > Scale Factor: 200% -* Display > Screen > HiDPI Support: Use unscaled HiDPI Output (checked) -* Display > Screen > Acceleration: Enable 3D acceleration (checked) - -##### Windows VM - -* Windows 10 64bit -* Recommended virtual disk size: 55 GB - -##### Linux VM - -* Ubuntu 16.04.4 64bit -* Recommended virtual disk size: 25 GB - -##### macOS VM - -* macOS X 10.11 (El Capitan) 64bit -* Recommended virtual disk size: 40 GB - -#### For every OS - -* Install latest security updates - -#### For Windows - -* Update AntiVirus Software and virus definitions -* Install [WiX toolset](https://wixtoolset.org/releases/) -* Run full AV system scan - -### Build release - -#### macOS - -To be able to generate a signed and notarized binary you have to have an Apple developer account and create the required -certificate and provisioning file before running the build. - -1. Make sure all version numbers are updated (update version variables and - run [replace_version_number.sh](https://github.com/bisq-network/bisq/blob/master/desktop/package/macosx/replace_version_number.sh)) - . - -2. Set environment variables to ~/.profile file or the like... (one time effort) - * `BISQ_GPG_USER`: e.g. export BISQ_GPG_USER=manfred@bitsquare.io - * `BISQ_SHARED_FOLDER`: shared folder that is used between your VM host and client system - * `BISQ_PACKAGE_SIGNING_IDENTITY`: e.g. "Developer ID Application: Christoph Atteneder (WQT93T6D6C)" - * `BISQ_PRIMARY_BUNDLE_ID`: e.g. "network.bisq.CAT" - * `BISQ_PACKAGE_NOTARIZATION_AC_USERNAME`: your Apple developer email address - * `BISQ_PACKAGE_NOTARIZATION_ASC_PROVIDER`: Your developer ID (e.g. WQT93T6D6C) - -3. Run `./gradlew --console=plain packageInstallers` - -Build output expected in shared folder: - -1. `Bisq-${NEW_VERSION}.dmg` macOS notarized and signed installer -2. `desktop-${NEW_VERSION}-all.jar.SHA-256` sha256 sum of fat jar -3. `jar-lib-for-raspberry-pi-${NEW_VERSION}.zip` Jar libraries for Raspberry Pi - -* Before building the other binaries install the generated Bisq app on macOS and verify that everything works as - expected. - -#### Linux - -1. Checkout the release tag in your VM - -2. Set environment variables to ~/.profile file or the like... (one time effort) - * `BISQ_SHARED_FOLDER`: shared folder that is used between your VM host and client system - -3. Run `./gradlew --console=plain packageInstallers` - -Build output expected: - -1. `bisq_${NEW_VERSION}-1_amd64.deb` package for distributions that derive from Debian -2. `bisq-${NEW_VERSION}-1.x86_64.rpm` package for distributions that derive from Redhat based distros -3. `desktop-${NEW_VERSION}-all.jar.SHA-256` sha256 sum of fat jar - -* Install and run generated package - -#### Windows - -To be able to generate a signed binary you have to apply and install a developer certificate before running the build. - -1. Checkout the release tag in your VM - -2. Set environment variables to ~/.profile file or the like... (one time effort) - * `BISQ_SHARED_FOLDER`: shared folder that is used between your VM host and client system - -3. Run `./gradlew --console=plain packageInstallers` - -Build output expected: - -1. `Bisq-${NEW_VERSION}.exe` Windows signed installer -2. `desktop-${NEW_VERSION}-all.jar.SHA-256` sha256 sum of fat jar - -* Install and run generated package - -### Sign release on macOS - -* Run [finalize.sh](https://github.com/bisq-network/bisq/blob/master/desktop/package/macosx/finalize.sh) - -Build output expected: - -1. `F379A1C6.asc` Sig key of Manfred Karrer -2. `5BC5ED73.asc` Sig key of Chris Beams -3. `29CDFD3B.asc`Sig key of Christoph Atteneder -4. `signingkey.asc` Fingerprint of key that was used for these builds -5. `Bisq-${NEW_VERSION}.dmg` macOS installer -6. `Bisq-${NEW_VERSION}.dmg.asc` Signature for macOS installer -7. `Bisq-64bit-${NEW_VERSION}.deb` Debian package -8. `Bisq-64bit-${NEW_VERSION}.deb.asc` Signature for Debian package -9. `Bisq-64bit-${NEW_VERSION}.rpm` Redhat based distro package -10. `Bisq-64bit-${NEW_VERSION}.rpm.asc` Signature for Redhat based distro package -11. `Bisq-64bit-${NEW_VERSION}.exe` Windows installer -12. `Bisq-64bit-${NEW_VERSION}.exe.asc` Signature for Windows installer - -* Run a AV scan over all files on the Windows VM where the files got copied over. - -### Final test - -* Make at least one mainnet test trade with some exotic currency to not interfere with real traders. - -### Tag and push release to master - -If all was successful: - -* commit changes of new version number (update version number for release of e.g. v1.5.0) -* create tag for the release - -``` - git tag -s v(new version, e.g. 1.5.0) -m"Release v(new version, e.g. 1.5.0)" -``` - -* Revert back to SNAPSHOT where necessary (change version variable (e.g. 1.5.0) in shell - script [insert_snapshot_version.sh](https://github.com/bisq-network/bisq/blob/master/desktop/package/macosx/insert_snapshot_version.sh) - and run it) and commit these changes. - -* Push all commits to master including the new tag - -``` - git push --tags origin master -``` - -### GitHub - -#### Upload preparations - -* Check the fingerprint of the pgp key which was used for signing in signingkey.asc (e.g. 29CDFD3B for Christoph - Atteneder) - -* Add all files including signingkey.asc and the gpg pub keys to GitHub release page - -* Check all uploaded files with [virustotal.com](https://www.virustotal.com) - -* Select the release tag as the source for the GitHub release. - -* Release on GitHub - -#### Post GitHub release - -* Apply “A newer version is already available! Please don’t use this version anymore.” to old GitHub releases. - -* Merge the webpage PR and check if they got deployed properly. - -* Start the Alert sender app (CMD + M) remove the old version and send the update message. Check the checkbox for - update, set the version number (e.g. 0.9.4) and add the short version of the release notes. - -* After sending the Update message leave it running for about 1 minute to give time for good propagation. - -* Make a backup of that alert sender app data directory - -* To support source code signature verification for Arch Linux download `Source code (tar.gz)`, sign it and upload - signature. - -``` - # sign source code bundle - gpg --digest-algo SHA256 --local-user $BISQ_GPG_USER --output bisq-${NEW_VERSION}.tar.gz.asc --detach-sig --armor bisq-${NEW_VERSION}.tar.gz - - # verify signature of source code bundle - gpg --digest-algo SHA256 --verify bisq-${NEW_VERSION}.tar.gz{.asc*,} -``` - -### Announce the release - -* Forum - -* Keybase (#general channel) - -* Twitter - -* Optionally reddit /r/Bisq - -* Notify @freimair so that he can start - updating [the Arch User Repository](https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=bisq-git) - -* Celebrate diff --git a/docs/testing.md b/docs/testing.md deleted file mode 100644 index 40158b891b..0000000000 --- a/docs/testing.md +++ /dev/null @@ -1,81 +0,0 @@ -# Bisq Testing Guide - -This guide describes the testing process performed prior to each release. - -## Prerequisites - -In order to take part in the testing process, you will need to do the following: - -- Build Bisq from source (see [build.md](build.md)) -- Setup a development/testing environment (see [Makefile](../Makefile) or [dev-setup.md](dev-setup.md)) -- Request access to [TestPad](https://bisq.ontestpad.com) (our test management tool) - -## Communication Channels - -If you would like to discuss and/or contribute to Bisq's testing effort, join us in the #testing channel within the [Bisq Keybase team](https://keybase.io/team/bisq). -Here you could also request access to TestPad (https://bisq.ontestpad.com). - -## Compensation - -Testing activities are eligible for [compensation](https://docs.bisq.network/dao/phase-zero.html#how-to-request-compensation). -When submitting a compensation request, please include links to artifacts on TestPad (results/reports) indicating the activities that were performed (e.g. tests that were executed), as well as any bugs that were discovered and entered as a result of testing. - -## Testing Process - -[TestPad](https://bisq.ontestpad.com) is used to manage and track the manual testing process. -For specific usage or functionality of TestPad, please see the flash card introduction within TestPad. - -### Definitions - -Some definitions within the context of TestPad and how they apply to our specific testing process: - -- **Project:** Defines a particular testing scope with relevant tests. -- **Script:** Each script is a collection of related tests that are intended to be used to test a particular component. -- **Folder:** Defines a group of scripts for each release. - -### Test Structure - -Tests are written using Behaviour-Driven Development (BDD) style syntax (given/when/then). -- **Given:** This states the preconditions that are assumed for the test. It is not a test step (one that requires a result to be recorded), but instead you must ensure the preconditions are satisfied in order to perform the test. -- **When:** This states the actions to be performed for the test. This also does not require a result to be recorded. -- **Then:** This states the expected results of the test. This requires a result to be recorded. - -### Testing Workflow - -Once logged in to TestPad, select the `Desktop Client` project from the left navigation menu. - -Each upcoming release will have a new folder created with applicable scripts that need to be executed. - -#### Executing a Script - -Test runs allow for tracking the results of test execution. Each script may have several test runs created in order to perform the tests on different environments (e.g. operating systems) and assigned to different people. An overview of all test runs for the release can be observed from the main project view, which allows you to quickly find test runs assigned to yourself. - -To execute a test run: - -1. Open the script to be executed. - -1. Hover over the applicable test run column and select the play button to start executing the test run. - -1. Follow the script and perform each test. - - - Select a status for each test. Select from one of the following statuses: - - - **Pass:** the test has passed successfully. - - **Fail:** there is an issue (defect) related to the test. - - **Blocked:** the test cannot be performed for a particular reason. - - **Query:** you are unsure about the test and require further information. - - **Exclude:** the test does not need to be performed for a particular reason. - - - If necessary, use the `Comments` field to add any comments, notes and actual test results. This is especially beneficial to provide details if a test did not pass. - - - If applicable, link an existing or create a new issue (defect) if it was found during the test run execution. - -### Creating Issues - -When creating issues, it is important to provide sufficient information describing the problem encountered. In addition to a clear and concise description, this may include attaching screenshots or log files if necessary so the assigned developer can identify and resolve the issue. - -### Testing Tips - -- **Test from a new users perspective.** In addition to looking for obvious errors, be on the lookout for any usability or workflow concerns. - -- **Reset the "don't show again" flags.** This will allow you to verify the popup messages are valid and appropriate.