Add wiki docs to the repo
This commit is contained in:
Vitaliy Vlasov
Martin Klepsch
parent
dffb6104a2
commit
6f366e3dc6
|
|
@ -0,0 +1,28 @@
|
||||||
|
This document describes process guidelines to be followed when contributing to Status Open Bounty repo.
|
||||||
|
|
||||||
|
First, make sure to familiarize yourself with the [README](https://github.com/status-im/open-bounty/blob/develop/README.md) and [Testing](https://github.com/status-im/open-bounty/blob/develop/doc/testing.md) documents in order to setup the project properly.
|
||||||
|
|
||||||
|
# Issues
|
||||||
|
- Issues should have type, priority and size (difficulty) assigned via corresponding labels
|
||||||
|
- Issue descriptions should include the following fields:
|
||||||
|
- **Summary**
|
||||||
|
- **Type**
|
||||||
|
- (*Features or enhancements only*) **User story**
|
||||||
|
- (*Bugs only*) **Expected behavior**
|
||||||
|
- (*Bugs only*) **Actual behavior**
|
||||||
|
- **Additional information**
|
||||||
|
|
||||||
|
# Pull requests
|
||||||
|
- Branch names should include:
|
||||||
|
- prefixes indicating issue type (`bug`, `feature`, `doc`, `test`)
|
||||||
|
- short description in lisp-case
|
||||||
|
- and include associated issue number
|
||||||
|
|
||||||
|
For instance, `bug/messy-problem-#1234`
|
||||||
|
- Start the title of the PR with [FIX #NNN], where #NNN is the issue number
|
||||||
|
- Always include `Status:` in the PR description to indicate whether PR is `WIP` or `Finished`.
|
||||||
|
- PR description should include the following sections:
|
||||||
|
- **Summary**
|
||||||
|
- **Notes**
|
||||||
|
- **Status**
|
||||||
|
- Merges into `develop` branch should be approved by at least 1 person, into `master` - by 2.
|
||||||
|
|
@ -0,0 +1,16 @@
|
||||||
|
# Deployment flow
|
||||||
|
|
||||||
|
This briefly describes events that occur when an issue is labeled as bounty and a new contract has to be deployed.
|
||||||
|
|
||||||
|
1. Issue is labeled
|
||||||
|
2. Event is received via GitHub App webhook
|
||||||
|
3. Contract is deployed
|
||||||
|
4. GitHub issue comment "Deploying contract..." is posted
|
||||||
|
5. `transaction_hash` is stored in the `issues` table
|
||||||
|
|
||||||
|
The following items execute in scheduler threads that run each minute, so up to 60 sec delay can be expected.
|
||||||
|
|
||||||
|
6. `update-issue-contract-address` scheduler thread fetches transaction receipt, updates `contract_address` and updates GitHub comment with a new image and current balance
|
||||||
|
7. `deploy-pending-contracts` scheduler thread checks if there are issues that did not have corresponding contracts deployed and attempts to redeploy
|
||||||
|
8. `update-balances` scheduler thread checks balances and updates GitHub comment accordingly
|
||||||
|
9. `update-contract-internal-balances` scheduler threads updates internal ERC20 token balances for all deployed contracts. This is required by current contract code
|
||||||
|
|
@ -0,0 +1,57 @@
|
||||||
|
# Payout flow
|
||||||
|
|
||||||
|
This describes the sequence of events happening once a PR for an issue with a bounty was merged by repo maintainer.
|
||||||
|
|
||||||
|
### Quick info on transaction hashes
|
||||||
|
In the sequence described below, several types of hashes are used. SOB checks presence of different hashes on records in the `issues` table to decide which action to take on an issue and associated contract. These hashes are:
|
||||||
|
- `transaction_hash`: set when contract is deployed to the labeled issue
|
||||||
|
- `execute_hash`: set when PR for an issue with a bounty was merged
|
||||||
|
- `confirm_hash`: fetched from receipt from transaction invoked in previous step
|
||||||
|
- `payout_hash`: set when payout was confirmed via `Manage Payouts`
|
||||||
|
|
||||||
|
The event flow is given below. For the bounty to be paid, each issue has to go through the steps in given order.
|
||||||
|
|
||||||
|
### 1. PR closed and merged
|
||||||
|
- app receives notification via GitHub App webhook (endpoint: `/webhook-app`)
|
||||||
|
- `handle-claim` fn is invoked which will:
|
||||||
|
- save PR in the `pull_requests` DB table, where state=1 for merged PRs
|
||||||
|
- update issue in the DB with commit SHA, if PR was merged
|
||||||
|
|
||||||
|
Afterwards two interleaving sequences of actions come into play: scheduler threads and manual user interaction in the `Manage Payouts` tab.
|
||||||
|
|
||||||
|
### 2. `self-sign-bounty` scheduler thread
|
||||||
|
- input query name: `pending-bounties`. This selects pending bounties (where `execute_hash` is nil and `commit_sha` is set)
|
||||||
|
- execute payout transactions
|
||||||
|
- store `execute_hash` and `winner_login` in `issues` DB table
|
||||||
|
- update GitHub comment to "Pending maintainer confirmation"
|
||||||
|
### 3. `update-confirm-hash` scheduler thread
|
||||||
|
- input query name: `pending-payouts`. This selects bounties with `execute_hash` set and no `confirm_hash`
|
||||||
|
- fetch `confirm_hash` from transaction receipt
|
||||||
|
- store `confirm_hash` in `issues` DB table
|
||||||
|
|
||||||
|
### 4. Manage Payouts view
|
||||||
|
In order to confirm a payout, following conditions have to be met for an issue:
|
||||||
|
- it is merged
|
||||||
|
- not paid yet (meaning its `payout_hash` is nil)
|
||||||
|
- not being confirmed at the moment (`:confirming?` flag is true)
|
||||||
|
OR
|
||||||
|
- already confirmed by a scheduler thread(`confirm_hash` is not nil)
|
||||||
|
|
||||||
|
Note that `confirm_hash` issue field and confirmation action in the UI are different things, albeit identically named. In order to confirm a payout from the UI, `confirm_hash` has to be already set by scheduler thread (see above).
|
||||||
|
|
||||||
|
Payout confirmation action results in a `:confirm-payout` event. Its handler will
|
||||||
|
- use `confirm_hash` to construct transaction payload
|
||||||
|
- set `:confirming?` flag to `true`
|
||||||
|
- execute `confirmTransaction()` call
|
||||||
|
- pass transaction callback to `confirmTransaction()`. Once invoked, the callback will:
|
||||||
|
- get `payout_hash` passed as an argument
|
||||||
|
- dispatch `:save-payout-hash` event. Its handler will:
|
||||||
|
- POST to /api/user/bounty/%s/payout
|
||||||
|
- This will update `payout_hash` in `issues` DB table
|
||||||
|
- if POST is successful, dispatch `:payout-confirmed`
|
||||||
|
- `:payout-confirmed` will update `:confirmed?` to `true` and remove `:confirming?` flag
|
||||||
|
|
||||||
|
### 5. `update-payout-receipt` scheduler thread
|
||||||
|
- input query name: `confirmed-payouts`. This selects confirmed payouts (the ones that have `payout_hash` and do not have `payout_receipt` set)
|
||||||
|
- store `payout_receipt` in `issues` DB table
|
||||||
|
- and update GitHub comment to "Paid to:..."
|
||||||
|
|
@ -0,0 +1,11 @@
|
||||||
|
# Common sync issues
|
||||||
|
|
||||||
|
- Repo rename. Related issue: https://github.com/status-im/open-bounty/issues/219.
|
||||||
|
- Transaction callback not executed, hence payout-hash not set.
|
||||||
|
- App downtime, multiple GitHub App deliveries failing. These can be afterwards replayed from GitHub App's Advanced tab.
|
||||||
|
- Geth issue. Not solvable on app end, Geth restart usually fixes these.
|
||||||
|
- Bot out of gas. Relevant issue: https://github.com/status-im/open-bounty/issues/195.
|
||||||
|
- Sometimes repos are disabled in DB (state=0), probably only happens to repos that were added earlier through OAuth App.
|
||||||
|
- PRs might end up in state=0 (opened) instead of state=1(merged), if PR did not have a proper text ("Fixes #..."). This one needs more investigation and more cases to reproduce.
|
||||||
|
- Sometimes contract_address cannot be fetched for a long period of time.
|
||||||
|
|
||||||
Loading…
Reference in New Issue