Merge pull request #46 from cbeams/roles

Produce 'Roles' doc

build.gradle

@@ -18,7 +18,10 @@ asciidoctor {
         icons               : 'font',
         idprefix            : '',
         idseparator         : '-',
-        docinfo1            : ''
+        docinfo1            : '',
+        'gh-org'            : 'https://github.com/bisq-network',
+        'gh-team'           : 'https://github.com/orgs/bisq-network/teams',
+        'role'              : 'https://github.com/bisq-network/roles/issues'
 }
 
 build.dependsOn asciidoctor

dao/phase-zero.adoc

@@ -425,27 +425,19 @@ See <<founder-use-cases>>.
 
 == Bonded contributor roles [[bonded-contributor-roles]]
 
-A _bonded contributor_ is a stakeholder who has put up a bond in BSQ in order to assume a _high-trust_ role within the DAO. High-trust roles are those that require privileged access such as a password or private key to perform, and more generally include any duties that can cause harm to the Bisq network or project if carried out incorrectly. As protection against malfeasance and gross negligence, BSQ bonds may be confiscated (burned) in part or in whole through stakeholder voting. In compensation for making their BSQ illiquid and incurring confiscation risk, bonded contributors earn interest in BSQ on their bonds; in compensation for carrying out the specific duties of their role, bonded contributors earn BSQ via the same compensation request process that applies to all other (non-bonded) contributors.
-
-While there are many specific bonded contributor roles, most fall into one of the categories below.
+NOTE: This section has been superseded by the <<../roles#, Roles>> document.
 
 === Maintainer
 
-A _maintainer_ is a bonded contributor responsible for a given repository in the <<bisq-network-org>>, including managing its issues, reviewing and merging pull requests and releasing new versions of the software in that repository.
-
-See <<maintainer-use-cases>>.
+NOTE: This section has been superseded by the <<../roles#maintainer, Maintainer>> section of the <<../roles#, Roles>> document.
 
 === Operator
 
-An _operator_ is a bonded contributor responsible for running ("operating") software that support the Bisq network. Examples include Bisq _seed node_ and _price node_ operators, the Bisq website operator, and the BSQ transaction explorer operator. Where practical, maintainer and operator roles may be played by the same contributor.
+NOTE: This section has been superseded by the <<../roles#operator, Operator>> section of the <<../roles#, Roles>> document.
 
 === Administrator
 
-An _administrator_ is a bonded contributor responsible for managing ("administering") applications and services that support the Bisq project. Examples include GitHub admin, DNS admin, Slack admin, IRC admin and Discourse (forum) admin.
-
-=== Other roles not listed here
-
-There are more than 30 bonded contributor roles in the Bisq project. See the <<roles-repo>> for a complete list.
+NOTE: This section has been superseded by the <<../roles#administrator, Administrator>> section of the <<../roles#, Roles>> document.
 
 
 = Appendix B: Resources [[Appendix-B]]
@@ -464,10 +456,12 @@ https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+org%3Abisq-network+label%3A
 
 https://github.com/bisq-network/compensation[https://github.com/bisq-network/compensation]
 
-=== roles repository and board [[roles-repo,bisq-network/roles repository]]
+=== roles repository [[roles-repo,bisq-network/roles repository]]
 
 https://github.com/bisq-network/roles[https://github.com/bisq-network/roles]
 
+See the <<../roles#, Roles>> document for full details.
+
 === proposals repository [[proposals-repo,bisq-network/proposals repository]]
 
 https://github.com/bisq-network/proposals[https://github.com/bisq-network/proposals]
@@ -581,30 +575,6 @@ NOTE: It is important to vote "no" if you believe a request should not be approv
 
 === modify this plan
 
-== As a bonded contributor, I can… [[bonded-contributor-use-cases,bonded contributor use cases]]
-
-=== earn interest on my BSQ bond
-
-=== transfer my role to the successor of my choosing
-
-== As a maintainer, I can… [[maintainer-use-cases,maintainer use cases]]
-
-=== post bounties
-
-In practice, "posting a bounty" simply means adding the `$BSQ bounty` label to a GitHub issue. Because maintainers are the only ones with write access to the repositories they maintain, they are the only ones with the ability to add this (or any other) label.
-
-The `$BSQ bounty` label should only be added to issues that are _ready for work_, meaning that they are already defined well enough to make it possible for a contributor to begin working on that bounty with a minimum amount of discussion.
-
-A well-defined bounty is one that clearly states a problem to be solved. If the desired solution is already known, the bounty should provide as much detail as necessary about that solution. If the solution is not already known, the maintainer may want to formulate the bounty as a request for a _proposal_ that can be reviewed and discussed, and then a subsequent bounty can address actually implementing that proposed solution.
-
-=== review and merge pull requests
-
-In accordance with the C4 process,footnoteref:[C4] all contributions to bisq-network repositories should come in the form of pull requests. Repository maintainers should review and comment on pull requests and merge them only if they are correct and well-formed.
-
-=== publish releases
-
-Maintainers are responsible for publishing releases of the software they maintain.
-
 == Post-phase zero use cases [[post-phase-zero-use-cases]]
 
 === As a stakeholder, I can sell BSQ on the Bisq exchange

index.adoc

@@ -48,6 +48,7 @@ Docs without hyperlinks haven't been written yet. If you want to write one, <<co
 
  * <<contributor-checklist#, Contributor Checklist>>
  * <<proposals#, Proposals>>
+ * <<roles#, Roles>>
  * <<exchange/howto/list-asset#, How to list an asset>>
  * <<manual-dispute-payout#, How to issue a manual dispute payout>>
  * <<exchange/howto/run-seednode#, How to run a seednode>>

proposals.adoc

@@ -1,51 +1,72 @@
 = Proposals
 
-Proposals are a means for suggesting specific changes to Bisq Network software components, infrastructure and processes. They are especially useful where awareness and agreement of other contributors is required in order for the change to be successfully implemented.
+Proposals are a means for suggesting changes to Bisq Network software components, infrastructure and processes.
 
 
 == Introduction
 
-The Bisq DAO is a flat organization, meaning that there is no command-and-control hierarchy available to make big decisions and carry them out.
+The Bisq DAO is a flat organization, with no command-and-control hierarchy available to make big decisions and carry them out. Usually this is not a problem, as most day-to-day changes happen without any need for organization-wide consensus. Certain kinds of changes, however, benefit from or even require it.
 
-Generally, this is not a problem, as the Bisq DAO is designed for contributors to operate permissionlessly and autonomously. Most day-to-day changes happen without any need for organization-wide consensus, but there are certain kinds of changes that benefit from or even require it. For such cases, what's needed is a mechanism that allows any contributor to _propose_ a change, and allows any and all other contributors to _review_ it in order to arrive at an IETF-style https://en.wikipedia.org/wiki/Rough_consensus[rough consensus] whether to proceed.
-
-_Proposals_ are that mechanism within the Bisq DAO, and this document covers everything that submitters, reviewers and maintainers need to know about the infrastructure, process and best practices around them.
+What's needed is a mechanism that allows any contributor to _propose_ a change, and all other contributors to _review_ it in order to arrive at an IETF-style rough consensus.footnote:[See link:https://en.wikipedia.org/wiki/Rough_consensus[]] _Proposals_ are that mechanism, and this document covers everything that participants need to know about the process.
 
 === What proposals are good for
 
-If you're thinking of creating an entire new Bisq component or making a significant change to an existing one, it's a good idea to submit a proposal first. Likewise, if you want to change something about the way contributors work together under the Bisq DAO, submit a proposal.
+ * Creating an entire new Bisq component or making a significant change to an existing one
+ * Changing something about the way contributors work together
 
 === What proposals are not good for
 
-For smaller changes to existing components, infrastructure or processes, where a broad consensus of contributors is not required, just submit an issue and/or pull request in the relevant repository. The maintainer of that repository will let you know if the change is too big or controversial, in which case they'll probably suggest you write a proposal. When in doubt, don't jump right to submitting a proposal. Have a conversation first. Chat with other contributors. See if they think a proposal is merited.
+ * Smaller changes to existing components, infrastructure or processes, where a broad consensus of contributors is not required
 
 
 == Infrastructure
 
 === GitHub
 
-Proposals are managed as GitHub issues in the https://github.com/bisq-network/proposals/issues[bisq-network/proposals] repository.
-
-TIP: If you're an active Bisq contributor, consider https://help.github.com/articles/watching-and-unwatching-repositories/[watching] this repository to be notified of new proposals and discussions around them. You can always https://help.github.com/articles/subscribing-to-and-unsubscribing-from-notifications/[unsubscribe] from specific issues you're not interested in.
+Proposals are managed as GitHub issues in the {gh-org}/proposals/issues[bisq-network/proposals] repository.
 
 === Slack
 
 The `#proposals` Slack channel is available for discussion and notifications about proposal issue activity.
 
 
-== Roles and responsibilities
+== Roles
 
 === Submitter
 
-The contributor(s) who write a proposal and carry it through to completion. **Submitters are 100% responsible for the success of their proposals.**
+The contributor(s) who write a proposal and carry it through to completion.
+
+**Submitters are 100% responsible for the success of their proposals.**
 
 === Reviewer
 
-Other contributors who read, discuss and react to proposals. **Any contributor _may_ review a proposal, but no contributor is obligated to do so.** This intentionally puts the onus on the submitter to ensure their proposal is relevant and well-written per the guidelines below.
+Other contributors who read, discuss and react to proposals.
+
+**Any contributor _may_ review a proposal, but no contributor is obligated to do so.** This intentionally puts the onus on the submitter to ensure their proposal is relevant and well-written per the <<guidelines>> below.
 
 === Maintainer
 
-The contributor(s) who have administrative rights over the `bisq-network/proposals` GitHub repository, monitor the `#proposals` Slack channel, enforce the process detailed below, and write https://github.com/bisq-network/roles/issues/30[monthly reports] on proposals activity. **Maintainers have no special authority to approve or reject proposals.**
+The contributor(s) responsible for proposals <<infrastructure>> and <<process>>.footnote:[See link:roles.html#maintainer[]]
+
+==== Role Issue
+
+{gh-org}/roles/issues/30[bisq-network/roles#30] footnote:[See link:roles.html#issue[]]
+
+==== Role Team
+:proposals-maintainers: {gh-team}/proposals-maintainers[@bisq-network/proposals-maintainers]
+
+{proposals-maintainers} footnote:[See link:roles.html#team[]]
+
+==== Duties
+
+ * Enforce the proposals <<process>> detailed below.
+ * Monitor communications on the `#proposals` Slack channel.footnote:[See link:roles.html#communication[]]
+ * Keep this proposals documentation up to date.footnote:[See link:roles.html#documentation[]]
+ * Write a monthly report on the proposals maintainer <<role-issue>>.footnote:[See link:roles.html#reporting[]]
+
+==== Rights
+
+ * Write access to the {gh-org}/proposals[bisq-network/proposals] repository.
 
 
 == Process
@@ -67,7 +88,7 @@ A maintainer will quickly review your proposal and will either (a) assign it to
 
 === Step 2. Review
 
-Once a proposal is submitted, a two-week review period follows. During this period, interested reviewers should read, discuss and ultimately react to the proposal as follows:
+Once a proposal is submitted, a two-week review period follows. During this period, interested reviewers should read, discuss and ultimately https://help.github.com/articles/about-conversations-on-github/#reacting-to-ideas-in-comments[react] to the proposal as follows:
 
  - 👍: I agree with the proposal and want to see it enacted
  - 😕: I am uncertain about the proposal and I need more information
@@ -79,7 +100,7 @@ If you do not understand or care about a given proposal, ignore it.
 
 Use comments on the proposal issue to discuss, ask questions, and get clarifications. Take lengthy discussions offline to Slack or elsewhere and then summarize them back on the issue.
 
-TIP: Remember that the proposal review process is all about reaching a _rough consensus,_ meaning that there is a broad agreement that the proposal should be enacted, and that any dissenting opinions have been addressed, though not necessarily fully resolved.
+NOTE: Remember that the proposal review process is all about reaching a _rough consensus,_ meaning that there is a broad agreement that the proposal should be enacted, and that any dissenting opinions have been addressed, though not necessarily fully resolved.
 
 === Step 3. Evaluate