Difference between revisions of "Roles"

From Bisq Wiki
Jump to navigation Jump to search
m (The Roles Maintainer role)
m (keybase > matrix)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This article is a stub pending the transcription of https://docs.bisq.network/roles.html here to the wiki. See https://github.com/bisq-network/roles/issues for the canonical list of all current roles and see [[:Category:Roles|Category:Roles]] for a list of all roles documented here on the wiki.
+
'''Roles''' are the way contributors take responsibility for Bisq network resources and processes.
  
Roles are the way contributors take responsibility for Bisq Network resources and processes.
+
__TOC__
 +
 
 +
== Background ==
  
__TOC__
+
There are many resources and processes vital to the operation of the Bisq Network that require ownership by individual contributors. For example, someone must merge pull requests into the <code>bisq</code> repository, someone must manage DNS for the <code>bisq.network</code> domain, a group of people must maintain critical infrastructure such as seed nodes and price nodes, etc.
  
=Introduction=
+
This document defines the system of roles used within the Bisq DAO to enumerate, define and track each of these responsibilities. The system is designed with two major goals in mind:
There are many resources and processes vital to the operation of the Bisq Network that require ownership by individual contributors. For example, someone must merge pull requests into the ''bisq-desktop'' repository, someone must manage DNS for the ''bisq.network'' domain, someone must conduct monthly stakeholder voting, and so on.
+
# To maximize role owner autonomy in order to achieve Bisq's [[Decentralized_autonomous_organization|decentralization goals]]
 +
# To maximize transparency so that DAO stakeholders can effectively review and vote on role owner compensation requests
  
This document defines the system of '''roles''' used within the Bisq DAO to enumerate, define and track each of these responsibilities. The system is designed with two major goals in mind:
+
== Properties ==
# To maximize role owner autonomy in order to achieve Phase Zero decentralization goals.
 
# To maximize transparency such that DAO stakeholders can effectively review and vote on role owner compensation requests.
 
  
=Properties=
 
 
The following are properties common to all roles.
 
The following are properties common to all roles.
  
==Duties==
+
=== Duties ===
'''Duties''' are actions that must be performed for a certain resource or process to function normally.
+
 
 +
''Duties'' are actions that must be performed for a certain resource or process to function normally.
 +
 
 
For example, a repository maintainer’s duties include merging pull requests in a timely fashion, and a website operator’s duties include keeping the site available at all times.
 
For example, a repository maintainer’s duties include merging pull requests in a timely fashion, and a website operator’s duties include keeping the site available at all times.
  
==Rights==
+
=== Rights ===
'''Rights''' are special permissions or other access required to perform the Duties of a role.
+
 
 +
''Rights'' are special permissions or other access required to perform the Duties of a role.
  
 
For example, a repository maintainer’s rights include write permissions to their repository, and a website operator’s rights include administrative access to site hosting infrastructure.
 
For example, a repository maintainer’s rights include write permissions to their repository, and a website operator’s rights include administrative access to site hosting infrastructure.
  
==Owners==
+
=== Owners ===
Owners are contributors who have the Rights required to perform the Duties of a role.
 
  
One owner is designated as primary and any other owners are designated as secondary.[https://github.com/bisq-network/proposals/issues/12 Propsal Link] The primary is responsible for performing the Duties of the role, while secondaries stand by, ready to take over for the primary at any time.
+
''Owners'' are contributors who have the Rights required to perform the Duties of a role.
  
=Infrastructure=
+
One owner is designated as primary and any other owners are designated as [https://github.com/bisq-network/proposals/issues/12 secondary]. The primary is responsible for performing the Duties of the role, while secondaries stand by, ready to take over for the primary at any time.
The following infrastructure is used to define and manage each role.
 
  
==Docs==
+
== Infrastructure ==
Each role should be documented at bisq.wiki, in a document of its own, under the Category [[Category:Roles]] and be references sections of larger documents dedicated to a resource or process in question.
 
  
For example, there is "[[Proposals Maintainer]]", and in the [[Proposals]] document it pulls it into the Maintainer section within.
+
The following infrastructure is used to define and manage each role.
  
Each role’s documentation should enumerate its Duties and Rights and link to its [[Category:Teams]] and Active Issue and Propsoal Issue.
+
=== Wiki ===
  
==Team==
+
Each role should be documented here on https://bisq.wiki in a document of its own, ideally linked to the larger resource or process it's related to.
Each role has a dedicated GitHub team where each of the role’s Owners are members. The team is used to manage access to GitHub repositories that the role is responsible for and to send notifications to role owners with @mentions in GitHub issues and pull requests.
 
  
For example, the [https://github.com/orgs/bisq-network/teams/desktop-maintainers/members @bisq-network/desktop-maintainers] team has write access to the [https://github.com/bisq-network/bisq-desktop bisq-network/bisq-desktop] repository.
+
For example, there is a [[Proposals|proposals wiki article]] covering the concept and process of proposals for users, and a [[Proposals_Maintainer|proposals maintainer article]] covering the role's rights, duties, and other details.
  
*GitHub teams are visible only to GitHub organization members. To join the [https://github.com/bisq-network @bisq-network] org, see the [[Contributor Checklist]].
+
Each role’s documentation should specify the role's:
 +
* duties
 +
* rights
 +
* GitHub team
 +
* GitHub issue
 +
* bonding requirement (if any)
  
The primary role owner is also assigned as the '''maintainer''' of their role’s GitHub team, such that they may manage the team without requiring the intervention of a GitHub admin.
+
=== Team ===
  
==Issue==
+
Each role has a dedicated GitHub team where each of the role’s Owners are members. The team is used to manage access to GitHub repositories that the role is responsible for and to send notifications to role owners with @mentions in GitHub issues and pull requests.
Each role has a dedicated GitHub issue in the [[https://github.com/bisq-network/roles/issues bisq-network/roles]] repository, wherein:
 
* The '''Assignees''' field is used to track role ownership.
 
* The '''Description''' field is used to link to the role’s Docs, Team and primary Owner.
 
* '''Comments''' are used for Reporting and feedback.
 
  
See the [https://github.com/bisq-network/roles/issues/30 Proposals Maintainer] role issue for an example.
+
For example, the [https://github.com/orgs/bisq-network/teams/bisq-maintainers @bisq-network/bisq-maintainers] team has write access to the [https://github.com/bisq-network/bisq bisq-network/bisq] repository.
  
=Types=
+
{{Admonition_Note|GitHub teams are visible only to GitHub organization members. To join the [https://github.com/bisq-network @bisq-network org], see the [[Contributor_checklist#Get_connected|contributor checklist]].}}
Most roles fit into one of the types below.
 
  
==Maintainer==
+
The primary role owner is also assigned as the ''maintainer'' of their role’s GitHub team, such that they may manage the team without requiring the intervention of a GitHub admin.
A ''Maintainer'' is a contributor responsible for enforcing process in a given GitHub repository.
 
  
Examples:  [https://github.com/bisq-network/roles/issues/63 Bisq Desktop Maintainer], [https://github.com/bisq-network/roles/issues/30 Proposals Maintainer].
+
=== Issue ===
  
===Maintainer Duties===
+
Each role has a dedicated GitHub issue in the [https://github.com/bisq-network/roles/issues bisq-network/roles] repository, wherein:
* Merging or closing pull requests after sufficient review.
+
* The '''Assignees''' field is used to track role ownership.
* Tagging releases.
+
* The '''Description''' field is used to link to the role’s wiki article, team, and primary owner.
* Triaging incoming issues and keeping them organized over time.
+
* '''Comments''' are used for reporting and feedback.
** A Maintainer is not a Developer or a Reviewer. Submitting and reviewing pull requests is something any contributor can do; neither are maintainer duties per se.
 
** This is particularly important from a [[Compensation]] perspective. '''If you are a maintainer, do NOT group your development and review activities together with your maintainer role in your compensation requests'''. Rather, account for them separately like any other contributor would.
 
** The goal is to have as many competent contributors developing and reviewing as possible, not to load everything on the maintainer. [https://rfc.unprotocols.org/spec:1/C4/#21-preliminaries C4] is the inspiration here, it’s worth (re-)reading.
 
  
===Maintainer Rights===
+
See the [Compensation Maintainer https://github.com/bisq-network/roles/issues/86] role issue for an example.
Write access to the repository they are responsible for.
 
  
==Operator==
+
== Types ==
An ''Operator'' is a contributor responsible for keeping a given resource running and functioning normally.
 
  
Examples: [https://github.com/bisq-network/roles/issues/19 Forum Operator], [https://github.com/bisq-network/roles/issues/14 Bisq Pricenode Operator].
+
Most roles fit into one of the types below.
  
===Operator Duties===
+
=== Maintainer ===
* Keep the given resource online and functioning normally.
 
* Keep the resource up to date with latest version.
 
* Maintain backups as appropriate.
 
* Report on any incidents.
 
  
===Operator Rights===
+
A ''Maintainer'' is a contributor responsible for enforcing process in a given GitHub repository.
* Administrative access to hosting infrastructure.
 
* Ownership of any domain name used.
 
  
==Administrator==
+
Examples: [https://github.com/bisq-network/roles/issues/63 Bisq Maintainer], [https://github.com/bisq-network/roles/issues/30 Proposals Maintainer]
An ''Administrator'' ('Admin') is a contributor responsible for managing a given resource.
 
  
Examples: [https://github.com/bisq-network/roles/issues/16 GitHub Admin], [https://github.com/bisq-network/roles/issues/23 Slack Admin].
+
==== Maintainer duties ====
  
===Admin Duties===
+
* Merging or closing pull requests after sufficient review
Respond to change requests.
+
* Tagging releases
 +
* Triaging incoming issues and keeping them organized over time
  
===Admin Rights===
+
'''A maintainer is not a developer or reviewer.'''
Access to the administrative interface of the resource in question.
 
  
==Moderator==
+
Submitting and reviewing pull requests is something any contributor can do; neither are maintainer duties per se.
A '''Moderator''' is a contributor responsible for enforcing process and standards in a given communications channel.
 
  
Examples: [https://github.com/bisq-network/roles/issues/37 Bitcointalk Moderator], [https://github.com/bisq-network/roles/issues/25 Reddit Moderator].
+
This is particularly important from a [[compensation]] perspective. If you are a maintainer, do NOT group your development and review activities together with your maintainer role in your compensation requests. Rather, account for them separately like any other contributor would.
  
===Moderator Duties===
+
The goal is to have as many competent contributors developing and reviewing as possible, not to load everything on the maintainer. [https://rfc.unprotocols.org/spec:1/C4/#21-preliminaries C4] is the inspiration here—it’s worth (re-)reading.
* Ensure discussions are on topic, civil, etc.
 
* Post key announcements in a timely fashion.
 
  
===Moderator Rights===
+
==== Maintainer rights ====
Moderator (or equivalent) status in the channel.
 
  
=Common duties=
+
* Write access to the repository they are responsible for
The following duties are common to all roles.
 
  
==Reporting==
+
=== Operator ===
Primary role Owners should report once a month in the form of a comment on their Issue.[https://github.com/bisq-network/proposals/issues/13 Proposal Link] The report should contain whatever information the owner believes would be valuable to other users, contributors and stakeholders. The comment should be formatted in Markdown as follows:
 
<nowiki>
 
## YYYY.MM report
 
  
<content>
+
An ''Operator'' is a contributor responsible for keeping a given resource running and functioning normally.
  
/cc bisq-network/compensation#<number>
+
Examples: [https://github.com/bisq-network/roles/issues/15 Seednode Operator], [https://github.com/bisq-network/roles/issues/19 Forum Operator]
</nowiki>
 
  
Where <content> is the content of the report itself, and <number> is the number of that contributor’s monthly compensation request. [https://github.com/bisq-network/proposals/issues/16#issuecomment-393852612 Example].
+
==== Operator duties ====
  
Some roles may have nothing to report in a given month. In this case, a report should still be written stating that there is "nothing to report". [https://github.com/bisq-network/proposals/issues/18#issuecomment-393217596 Example].
+
* Keep the given resource online and functioning normally
 +
* Keep the resource up to date with latest version
 +
* Maintain backups as appropriate
 +
* Report on any incidents
  
==Documentation==
+
==== Operator rights ====
Primary role Owners should document changes to their role by updating the Role on the wiki [[Category:Roles]].
 
  
==Communication==
+
* Administrative access to hosting infrastructure
Primary role Owners should respond in a timely fashion to feedback comments on their role Issue, issues created in their repositories, @mentions of their Team, and questions in their Slack channel.
+
* Ownership of any domain name used
  
=Compensation=
+
=== Administrator ===
Role owners should include a summary line item for each role they own in a monthly [[Compensation#Create_your_compensation_request_issue|compensation request]]. Each summary should include:
 
# The name of the role,
 
# a link to the owner’s monthly report for that role, and
 
# the total amount of BSQ being requested for performing the role’s duties during that month.
 
<nowiki>
 
Example 1. Per-role line items in a compensation request
 
Bisq Desktop Maintainer: bisq-network/roles#63 (comment) (350 BSQ)
 
  
Bisq Seednode Operator: bisq-network/roles#15 (comment) (150 BSQ)
+
An ''Administrator'' (often referred to as 'Admin') is a contributor responsible for managing a given resource.
</nowiki>
 
  
* Secondary role owners should not submit monthly reports or compensation requests for a role unless they actually performed the duties of that role during that month.
+
Examples: [https://github.com/bisq-network/roles/issues/16 GitHub Admin]
  
The amount of BSQ requested should include any hard costs (e.g. hosting) plus time and effort costs involved in performing the duties of the role. These costs should be detailed in the monthly report as follows:
+
==== Admin duties ====
<nowiki>
 
Example 2. Monthly report for Bisq Desktop Maintainer
 
## 2018.07 report
 
  
Regular duties (150 BSQ)
+
* Respond to change requests
  
Big issue cleanup (200 BSQ)
+
==== Admin rights ====
  
Total: 350 BSQ
+
* Access to the administrative interface of the resource in question
  
/cc bisq-network/compensation#42
+
== Common duties ==
</nowiki>
 
<nowiki>
 
  
Example 3. Monthly report for Bisq Seednode Maintainer
+
The following duties are common to all roles.
## 2018.07 report
 
  
Hosting 2 nodes @ 50 USD/mo on Digital Ocean (100 BSQ)
+
=== Reporting ===
  
Upgrade nodes to v0.7.1 (50 BSQ)
+
Primary role owners should report once a cycle in the form of a comment [https://github.com/bisq-network/proposals/issues/13 on their issue]. The report should contain whatever information the role owner believes would be valuable to other users, contributors, and stakeholders.  
  
Total: 150 BSQ
+
The comment should be formatted in Markdown as follows:
  
/cc bisq-network/compensation#42
+
## Cycle 21 Report
</nowiki>
+
 +
Description and/or list of contributions, accomplishments, or other notable occurrences since the last role report was posted.
 +
 +
/cc bisq-network/compensation#421
  
The only work items that should be included in role compensation are those Duties that can be performed only by that role’s owner. Everything else should be itemized independently.
+
The <code>/cc</code> part should reference the GitHub issue for the contributor's compensation request for the cycle corresponding to the role report.
  
For example, as mentioned above in the Maintainer Duties section, a repository maintainer’s main duties are merging pull requests and triaging incoming issues. If the person playing the maintainer role submits their own pull requests, or performs reviews of others' pull requests, that work should NOT be grouped together with regular maintainer duties when putting together a compensation request. Rather, each PR submitted or reviewed should be called out separately as individual contributions.
+
== Bonding ==
  
=Bonding=
+
Most roles involve special rights that, if abused, could cause damage to the Bisq Network. For this reason, [[Introduction_to_the_DAO#Ensure_honesty_in_high-trust_roles|role owners must put up a bond in BSQ]] [https://github.com/bisq-network/bisq/blob/master/core/src/main/java/bisq/core/dao/state/model/governance/BondedRoleType.java commensurate with the amount of damage that could be caused]. In the event of a role owner turning into a bad actor or being grossly negligent, this bond can be confiscated through a Bisq DAO proposal for confiscating a bond.
Most roles involve special Rights that, if abused, could cause damage to the Bisq Network. For this reason, role owners must put up a ''bond'' in BSQ commensurate with the amount of damage that could be caused. In the event of a role owner turning into a bad actor or being grossly negligent, this bond can be confiscated through a BSQ voting process.
 
  
Bonding is currently in a transitional state, the expected bond will be found in the respective Role Page.
+
== Processes ==
  
=Processes=
 
 
The following are some common roles-related processes.
 
The following are some common roles-related processes.
  
==Proposing a new role==
+
=== Proposing a new role ===
 +
 
 
Typically, proposing a new role is one part of a larger proposal to introduce some new resource or process.
 
Typically, proposing a new role is one part of a larger proposal to introduce some new resource or process.
  
# Discuss the idea informally with other contributors, e.g. via [Keybase].
+
# Discuss the idea informally with other contributors, e.g. via [https://bisq.chat Matrix]
# Follow the [[Proposals]] process to formally suggest the new resource or process.
+
# Follow the [[proposals]] process to formally suggest the new resource or process
# Draft documentation for the new resource or process, including a section about the new role, tagged as [WIP] on the Wiki.
+
# Draft documentation for the new resource or process, including an article about the new role as a wiki article
  
For example, see the [https://github.com/bisq-network/proposals/15 proposal to support Tor Relays] and the resulting [https://github.com/bisq-network/proposals/72 Tor Relay Operator] role issue.
+
=== Adding a secondary role owner ===
  
==Adding a secondary role owner==
 
 
A primary role owner may add a secondary owner with the following steps:
 
A primary role owner may add a secondary owner with the following steps:
 +
 
# Add them as a member of the role’s GitHub Team.
 
# Add them as a member of the role’s GitHub Team.
 
# Add them as an assignee to role’s GitHub Issue.
 
# Add them as an assignee to role’s GitHub Issue.
 
# Announce the change via a comment on the role’s GitHub Issue.
 
# Announce the change via a comment on the role’s GitHub Issue.
  
==Transferring role ownership==
+
=== Transferring role ownership ===
A primary owner may transfer ownership to another with the following steps:
+
 
# Grant the ''maintainer'' role to the new primary in the role’s GitHub Team.
+
A role owner may transfer ownership to another with the following steps:
# Remove the ''maintainer'' role from yourself.
+
 
# Update the role’s GitHub Issue to reflect the new primary owner.
+
# Get the new contributor added to the role’s GitHub team.
 +
# Get the old contributor removed from the role's GitHub team.
 +
# Have the role’s GitHub issue updated to reflect the new primary owner.
 
# Announce the change in a comment on the role’s GitHub Issue.
 
# Announce the change in a comment on the role’s GitHub Issue.
 
=The Roles Maintainer role=
 
{{:Roles_Maintainer}}
 

Latest revision as of 19:18, 22 January 2022

Roles are the way contributors take responsibility for Bisq network resources and processes.

Background

There are many resources and processes vital to the operation of the Bisq Network that require ownership by individual contributors. For example, someone must merge pull requests into the bisq repository, someone must manage DNS for the bisq.network domain, a group of people must maintain critical infrastructure such as seed nodes and price nodes, etc.

This document defines the system of roles used within the Bisq DAO to enumerate, define and track each of these responsibilities. The system is designed with two major goals in mind:

  1. To maximize role owner autonomy in order to achieve Bisq's decentralization goals
  2. To maximize transparency so that DAO stakeholders can effectively review and vote on role owner compensation requests

Properties

The following are properties common to all roles.

Duties

Duties are actions that must be performed for a certain resource or process to function normally.

For example, a repository maintainer’s duties include merging pull requests in a timely fashion, and a website operator’s duties include keeping the site available at all times.

Rights

Rights are special permissions or other access required to perform the Duties of a role.

For example, a repository maintainer’s rights include write permissions to their repository, and a website operator’s rights include administrative access to site hosting infrastructure.

Owners

Owners are contributors who have the Rights required to perform the Duties of a role.

One owner is designated as primary and any other owners are designated as secondary. The primary is responsible for performing the Duties of the role, while secondaries stand by, ready to take over for the primary at any time.

Infrastructure

The following infrastructure is used to define and manage each role.

Wiki

Each role should be documented here on https://bisq.wiki in a document of its own, ideally linked to the larger resource or process it's related to.

For example, there is a proposals wiki article covering the concept and process of proposals for users, and a proposals maintainer article covering the role's rights, duties, and other details.

Each role’s documentation should specify the role's:

  • duties
  • rights
  • GitHub team
  • GitHub issue
  • bonding requirement (if any)

Team

Each role has a dedicated GitHub team where each of the role’s Owners are members. The team is used to manage access to GitHub repositories that the role is responsible for and to send notifications to role owners with @mentions in GitHub issues and pull requests.

For example, the @bisq-network/bisq-maintainers team has write access to the bisq-network/bisq repository.

Note
GitHub teams are visible only to GitHub organization members. To join the @bisq-network org, see the contributor checklist.

The primary role owner is also assigned as the maintainer of their role’s GitHub team, such that they may manage the team without requiring the intervention of a GitHub admin.

Issue

Each role has a dedicated GitHub issue in the bisq-network/roles repository, wherein:

  • The Assignees field is used to track role ownership.
  • The Description field is used to link to the role’s wiki article, team, and primary owner.
  • Comments are used for reporting and feedback.

See the [Compensation Maintainer https://github.com/bisq-network/roles/issues/86] role issue for an example.

Types

Most roles fit into one of the types below.

Maintainer

A Maintainer is a contributor responsible for enforcing process in a given GitHub repository.

Examples: Bisq Maintainer, Proposals Maintainer

Maintainer duties

  • Merging or closing pull requests after sufficient review
  • Tagging releases
  • Triaging incoming issues and keeping them organized over time

A maintainer is not a developer or reviewer.

Submitting and reviewing pull requests is something any contributor can do; neither are maintainer duties per se.

This is particularly important from a compensation perspective. If you are a maintainer, do NOT group your development and review activities together with your maintainer role in your compensation requests. Rather, account for them separately like any other contributor would.

The goal is to have as many competent contributors developing and reviewing as possible, not to load everything on the maintainer. C4 is the inspiration here—it’s worth (re-)reading.

Maintainer rights

  • Write access to the repository they are responsible for

Operator

An Operator is a contributor responsible for keeping a given resource running and functioning normally.

Examples: Seednode Operator, Forum Operator

Operator duties

  • Keep the given resource online and functioning normally
  • Keep the resource up to date with latest version
  • Maintain backups as appropriate
  • Report on any incidents

Operator rights

  • Administrative access to hosting infrastructure
  • Ownership of any domain name used

Administrator

An Administrator (often referred to as 'Admin') is a contributor responsible for managing a given resource.

Examples: GitHub Admin

Admin duties

  • Respond to change requests

Admin rights

  • Access to the administrative interface of the resource in question

Common duties

The following duties are common to all roles.

Reporting

Primary role owners should report once a cycle in the form of a comment on their issue. The report should contain whatever information the role owner believes would be valuable to other users, contributors, and stakeholders.

The comment should be formatted in Markdown as follows:

## Cycle 21 Report

Description and/or list of contributions, accomplishments, or other notable occurrences since the last role report was posted.

/cc bisq-network/compensation#421

The /cc part should reference the GitHub issue for the contributor's compensation request for the cycle corresponding to the role report.

Bonding

Most roles involve special rights that, if abused, could cause damage to the Bisq Network. For this reason, role owners must put up a bond in BSQ commensurate with the amount of damage that could be caused. In the event of a role owner turning into a bad actor or being grossly negligent, this bond can be confiscated through a Bisq DAO proposal for confiscating a bond.

Processes

The following are some common roles-related processes.

Proposing a new role

Typically, proposing a new role is one part of a larger proposal to introduce some new resource or process.

  1. Discuss the idea informally with other contributors, e.g. via Matrix
  2. Follow the proposals process to formally suggest the new resource or process
  3. Draft documentation for the new resource or process, including an article about the new role as a wiki article

Adding a secondary role owner

A primary role owner may add a secondary owner with the following steps:

  1. Add them as a member of the role’s GitHub Team.
  2. Add them as an assignee to role’s GitHub Issue.
  3. Announce the change via a comment on the role’s GitHub Issue.

Transferring role ownership

A role owner may transfer ownership to another with the following steps:

  1. Get the new contributor added to the role’s GitHub team.
  2. Get the old contributor removed from the role's GitHub team.
  3. Have the role’s GitHub issue updated to reflect the new primary owner.
  4. Announce the change in a comment on the role’s GitHub Issue.