Skip to content
This repository has been archived by the owner on Jun 15, 2021. It is now read-only.

Commit

Permalink
Revise entire Roles document
Browse files Browse the repository at this point in the history
This is a full pass over the doc with changes to nearly every section.
Several sections remain incomplete.
  • Loading branch information
cbeams committed Jul 1, 2018
1 parent 9048e4c commit 6c030fa
Showing 1 changed file with 54 additions and 65 deletions.
119 changes: 54 additions & 65 deletions roles.adoc
Original file line number Diff line number Diff line change
@@ -1,74 +1,71 @@
= Bisq DAO Roles
= Roles

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


== Introduction

The Bisq DAO is a flat organization, without traditional management or reporting structures. At the same time, there are many vital resources and processes that must be cared for by individuals. For example, someone must manage the DNS for the `bisq.network` domain, someone must conduct monthly stakeholder voting, and so on.
The Bisq DAO is a flat organization, without traditional management or reporting structures. At the same time, there are many resources and processes vital to the operation of the network that must be cared for by individuals. For example, someone must manage the DNS for the `bisq.network` domain, someone must conduct monthly stakeholder voting, and so on. What's needed is a mechanism that defines these various duties, makes it clear who is responsible for each, and that provides a process for regular reporting and feedback. The system of _roles_ described below is designed to meet this need, with a major design goal being maximizing decentralization and keeping the organization flat as it grows.

What's needed is a mechanism that defines these various duties, makes it clear who is responsible for each, and that includes a process for regular reporting and feedback. The system of _roles_ described below provides such a mechanism.

== Properties

[[characteristics]]
== Characteristics of a role
The following are properties common to all roles.

=== Duties

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 the 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

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 the 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

Contributors who have the <<rights>> required to perform the <<duties>> of a role.
_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_.footnote:[See {gh-org}/proposals/issues/12] The primary is responsible for performing the <<duties>> of the role, while secondaries stand by, capable of taking over for the primary at any time.


== Infrastructure

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

=== Docs

There is no "role documentation" per se, but rather there is documentation about whatever component or infrastructure a given role is responsible for, and in that documentation, there is a section for the role.
Each role should be documented at https://docs.bisq.network[docs.bisq.network], not in a document of its own, but in a _section_ of a document dedicated to the larger resource or process in question.

For example, there is no "Proposals Maintainer" document, but rather a <<proposals#, Proposals>> document having a <<proposals#maintainer, Maintainer>> section within.

=== GitHub
Each role's documentation should enumerate its <<duties>> and <<rights>> and link to its <<team>> and <<issue>>.

==== Issues
=== Team

Roles are managed as issues in the {gh-org}/roles/issues[bisq-network/roles] repository.
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 role is responsible for and to send notifications to owners with @mentions in GitHub issues and pull requests.

////
- Assignees used to track role ownership
- Description field used to
- Link to team
- Indicate who is primary
- Link to role documentation
- Comments used for
- monthly reporting
- customer feedback
- Anyone can subscribe to any issue or watch the whole repo to stay up to date with reporting
- Labels used to
- Indicate `help wanted`
////
For example, the {gh-team}/desktop-maintainers/members[@bisq-network/desktop-maintainers] team has write access to the {gh-org}/bisq-desktop[bisq-network/bisq-desktop] repository.

==== Teams
The primary role owner is also assigned as the _maintainer_ of the GitHub team, such that they may manage the team without requiring the intervention of a GitHub admin.

Managed as GitHub Teams. For @mentions and to institutionalize thinking in terms of roles not individuals.
=== Issue

=== Slack
Each role has a dedicated GitHub issue in the {gh-org}/roles/issues[bisq-network/roles] repository.

Slack.
- The **Assignees** field is used to track role ownership.
- The **Description** field is used to link to the role's <<docs>>, <<team>> and primary <<owners, Owner>>.
- **Comments** are used for <<report, reporting>> and feedback.

See the {gh-org}/roles/issues/30[Proposals Maintainer] role issue for an example.


== Types

Most roles fit into one of the types below.

=== Maintainer

=== Operator
Expand All @@ -78,11 +75,13 @@ Slack.
=== Moderator


== Common role duties
== Common duties

=== Reporting
The following duties are common to all roles.

Primary role <<owners>> should submit a _monthly report_ as a comment on their <<issues, Role Issue>>.footnote:[See {gh-org}/proposals/issues/13] 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:
=== Report

Primary role <<owners>> should report once a month in the form of a comment on their <<issue>>.footnote:[See {gh-org}/proposals/issues/13] 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:

[source,markdown]
----
Expand All @@ -97,62 +96,52 @@ Where `<content>` is the content of the report itself, and `<number>` is the num

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/roles/issues/18#issuecomment-393217596[Example].

=== Communication

Respond to issues in any repositories

Respond to inquiries in Slack
=== Document

Generally means setting up notifications appropriately.
Primary role <<owners>> should document changes to their role by submitting pull requests to their role's <<docs>>.

=== Documentation
=== Communicate

Specifically, keeping your own role's documentation up to date
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.


== Compensation

TODO


== Bonding

////
In the section below, custom [[anchors]] are used for each section to disambiguate them from sections with the same name in the general documentation above about role issues, role teams, duties, rights and owners.
////
TODO


[[roles-maintainer-role]]
== The Roles Maintainer role

The contributor(s) responsible for roles <<infrastructure>> and <<processes>>.footnote:[See link:roles.html#maintainer[]]
Roles Maintainers are the contributors responsible for the system of roles described throughout the rest of this document.

[[roles-maintainer-role-issue]]
=== Role Issue
[[roles-maintainer-issue]]
=== Issue

{gh-org}/issues/28[#28]
{gh-org}/roles/issues/28[bisq-network/roles#28]

[[roles-maintainer-role-team]]
=== Role Team
:roles-maintainers: {gh-team}/roles-maintainers[@bisq-network/roles-maintainers]
[[roles-maintainer-team]]
=== Team

{roles-maintainers} footnote:[See link:roles.html#teams[]]
{gh-team}/roles-maintainers[@bisq-network/roles-maintainers]

[[roles-maintainer-duties]]
=== Duties

* Enforce the proposals <<processes>> detailed below.
* Monitor communications on the `#roles` Slack channel.footnote:[See link:roles.html#communication[]]
* Keep this roles documentation up to date.footnote:[See link:roles.html#documentation[]]
* Write a monthly report on the roles maintainer <<roles-maintainer-role-issue>>.footnote:[See link:roles.html#reporting[]]
* Follow and enforce the roles <<processes>> detailed below.
* <<report>> monthly on the Roles Maintainer <<roles-maintainer-issue>>.
* <<document>> changes to roles <<processes>>.
* <<communicate>> in the `#roles` Slack channel.

[[roles-maintainer-rights]]
=== Rights

* Membership in the {roles-maintainers} team
* `Maintainer` status in the {roles-maintainers} team (primary owner only)
* Write access to the {gh-org}/roles[bisq-network/roles] repository (through the {roles-maintainers} team)

[[roles-maintainer-owners]]
=== Owners

See the <<roles-maintainer-role-issue>>
* Write access to the {gh-org}/roles[bisq-network/roles] repository


== Processes
Expand Down

0 comments on commit 6c030fa

Please sign in to comment.