Difference between revisions of "Proposals"

From Bisq Wiki
Jump to navigation Jump to search
(miograted from https://docs.bisq.network/proposals.html)
m (keybase > matrix)
 
(11 intermediate revisions by 4 users not shown)
Line 1: Line 1:
Proposals are a means for suggesting changes to Bisq Network software components, infrastructure and processes.
+
'''Proposals''' are a way to suggest significant ''project-wide'' changes or new initiatives where a broad consensus of contributors, users, and stakeholders is desired. Smaller changes to existing components, infrastructure, or processes are generally best discussed in other channels (on Matrix, other GitHub repositories, etc).
 +
 
 +
This article covers the roles, processes, and conventions for proposals.
 +
 
 
__TOC__
 
__TOC__
=Introduction=
 
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.
 
  
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 [https://en.wikipedia.org/wiki/Rough_consensus rough consensus]. ''Proposals'' are that mechanism, and this document covers everything that participants need to know about the process.
+
== Roles ==
 +
 
 +
* [[Proposals Maintainer]]
 +
 
 +
== Processes ==
 +
 
 +
Anyone may submit new proposals and/or review other proposals. But there are things you can do to make it more likely your ideas are received well.
 +
 
 +
=== Submission and Review ===
 +
 
 +
==== Research and Evaluate ====
  
==What proposals are good for==
+
Proposals are supposed to be significant items with enough weight to draw attention from core contributors, users, and stakeholders from across functions.
* 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==
+
{{Admonition_Note|If your idea is focused on a particular area of Bisq, it would be best to first float your idea in the channels for that area. For example, development-related ideas can be discussed in #dev on Matrix or in [https://github.com/bisq-network/bisq the main GitHub repository]. Growth-related ideas can be discussed in #growth on Matrix or the [https://github.com/bisq-network/growth/ growth GitHub repository].}}
* Smaller changes to existing components, infrastructure or processes, where a broad consensus of contributors is not required
 
  
=Infrastructure=
+
Accordingly, proposals should be well-considered, well-researched, and well-articulated.
==GitHub==
 
Proposals are managed as GitHub issues in the [https://github.com/bisq-network/proposals/issues bisq-network/proposals] repository.
 
  
==Keybase==
+
As a result, before submitting a proposal, please:
The #proposals [[Keybase]] channel is available for discussion and notifications about proposal issue activity.
+
# Discuss your idea with other contributors to see if a proposal is worth submitting at all
 +
# Search through existing proposals (both [https://github.com/bisq-network/proposals/issues open and closed]) to see whether something similar has already been proposed
 +
# Notice which among those proposals have been accepted and rejected, and why
 +
# Read this article to fully understand the proposal process and guidelines
  
=Roles=
+
Look through past proposals that succeeded to get a feel for how they were structured.
  
==Submitter==
+
==== Create GitHub Issue ====
The contributor(s) who write a proposal and carry it through to completion.
 
'''Submitters are 100% responsible for the success of their proposals.'''
 
  
==Reviewer==
+
Once you've done research, floated your idea in the community in other channels, and think your idea might garner broader support, create a new GitHub issue in the [https://github.com/bisq-network/proposals/issues|bisq-network/proposals repository on GitHub], written and formatted according to the following guidelines:
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==
+
* Write your proposal in a way that makes it as easy as possible to achieve rough consensus. This means that proposals should be as simple, focused, concrete and well-defined as possible. Your goal should be to make it as easy as possible for your fellow contributors to understand and agree with you.
 +
* Take full responsibility for your proposal. It is not the maintainers' job, nor anyone else’s, to see your proposal succeed. If people aren’t responding or reacting to your proposal, it’s your job to solicit that feedback more actively.
 +
* Never assume that anyone other than yourself is going to do the work described in your proposal. If your proposal does place expectations on other contributors, or requires them to change their behavior in any way, be explicit about that.
 +
* Provide context. Make a strong case for your proposal. Link to prior discussions. Do not make your reader do any more work than they have to to understand your proposal.
 +
* Format your proposal well. Make it a pleasure to read.
  
{{{:Proposals_Maintainer}}}
+
In general, good proposals take time to research and write. Every minute you spend clearly and logically articulating your proposal is a minute that you save other contributors in understanding it. This diligence on your part will be appreciated and rewarded by others' attention.
  
=Process=
+
{{Admonition_Warn|Cheaply-written, "drive by" proposals that waste others' time will be closed immediately as <code>was:incorrect</code>.}}
  
==Step 0. Research==
+
A [[Proposals_maintainer|maintainer]] will quickly review your proposal and will either (a) assign it to you to indicate your ownership and responsibility over it, or (b) close it and label it as <code>was:incorrect</code> if it does not follow the guidelines listed above.
Before you submit a proposal, '''do your homework!'''
 
# Discuss your idea with other contributors to see if a proposal is worth submitting at all;
 
# Search through existing proposals (both [https://github.com/bisq-network/proposals/issues?utf8=%E2%9C%93&q=is%3Aissue+ open and closed]) to see whether something similar has already been proposed;
 
# Notice which among those proposals have been accepted and rejected, and why;
 
# Read this document to fully understand the proposal process and guidelines.
 
  
==Step 1. Submit==
+
==== Review ====
Create a new GitHub issue in the [https://github.com/bisq-network/proposals/issues bisq-network/proposals] repository containing the text of your proposal, written and formatted per the guidelines below.
 
  
A maintainer will quickly review your proposal and will either (a) assign it to you to indicate your ownership and responsibility over it, or (b) close it and label it as ''was:incorrect'' if it does not follow the guidelines below.
+
Once a proposal is submitted, a two-week review period follows.  
  
==Step 2. Review==
+
During this period, interested reviewers should read, discuss and ultimately [https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-conversations-on-github#reacting-to-ideas-in-comments 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 agree with the proposal and want to see it enacted
+
* 😕: I am uncertain about the proposal and I need more information.
* 😕: I am uncertain about the proposal and I need more information
+
* 👎: I disagree with the proposal and do not want to see it enacted.
* 👎: I disagree with the proposal and do not want to see it enacted
 
  
When reacting with a 😕 or 👎, add a comment explaining why. If you don’t, then don’t expect your opinion to have much weight or get addressed.
+
Try to provide an explanation of your reaction, especially when reacting with a 😕 or 👎. If you don’t, then don’t expect your opinion to have much weight or get addressed.
  
 
If you do not understand or care about a given proposal, ignore it.
 
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.
+
Use comments on the proposal issue to discuss, ask questions, and get clarifications. Take lengthy discussions offline to Matrix or elsewhere and then summarize them back on the issue.
 +
 
 +
==== Evaluate ====
  
* 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.
+
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==
 
 
After the two-week review period is over, a maintainer will evaluate reactions to and discussions about the proposal and will close the issue with a comment explaining that it is approved or rejected based on whether a rough consensus was achieved.
 
After the two-week review period is over, a maintainer will evaluate reactions to and discussions about the proposal and will close the issue with a comment explaining that it is approved or rejected based on whether a rough consensus was achieved.
  
Approved proposals will be labeled with ''was:approved.'' Rejected proposals will be labeled with ''was:rejected.''
+
Approved proposals will be labeled with <code>was:approved</code>. Rejected proposals will be labeled with <code>was:rejected</code>.
  
If rough consensus has not been achieved, e.g. because discussion is still ongoing, dissenting concerns have not been addressed, or the proposal has turned out to be contentious, the maintainer will indicate that they cannot close the proposal, and that it is up to the submitter to take next steps to move the proposal forward. If the proposal does not move forward after another two weeks, the maintainer will close and label it ''was:stalled''.
+
If rough consensus has not been achieved, e.g. because discussion is still ongoing, dissenting concerns have not been addressed, or the proposal has turned out to be contentious, the maintainer will indicate that they cannot close the proposal, and that it is up to the submitter to take next steps to move the proposal forward. One option is to [[#Submit_to_the_DAO|submit the proposal to the DAO]] for voting. If the proposal does not move forward after another two weeks, the maintainer will close and label it <code>was:stalled</code>.
  
If there have been no or very few reactions to a proposal after the two-week period, the maintainer will close it and label it as ''was:ignored''.
+
If there have been no or very few reactions to a proposal after the two-week period, the maintainer will close it and label it as <code>was:ignored</code>.<!-- was:moved-->
  
==Step 4. Enact==
+
==== Enact ====
Assuming your proposal was approved, the next step is to actually enact the changes described in that proposal.
 
  
=Guidelines=
+
Assuming your proposal was approved, the next step is to actually enact the changes described in that proposal, perhaps by [[Project_management|creating a project]] or simply getting to work.
Write your proposal in a way that makes it as easy as possible to achieve rough consensus. This means that proposals should be as simple, focused, concrete and well-defined as possible. Your goal should be to make it as easy as possible for your fellow contributors to understand and agree with you.
 
  
Take full responsibility for your proposal. It is not the maintainers' job, nor anyone else’s, to see your proposal succeed. If people aren’t responding or reacting to your proposal, it’s your job to solicit that feedback more actively.
+
=== Submit to the DAO (if needed) ===
  
Never assume that anyone other than yourself is going to do the work described in your proposal. If your proposal does place expectations on other contributors, or requires them to change their behavior in any way, be explicit about that.
+
Sometimes it is necessary to submit proposals to the DAO for voting:
 +
* DAO parameter changes
 +
* proposal for bonded roles
 +
* contentious proposals for which there is strong interest but no clear consensus
  
Provide context. Make a strong case for your proposal. Link to prior discussions. Do not make your reader do any more work than they have to to understand your proposal.
+
For most general proposals this should not be necessary—general proposals that have clear consensus (or clear lack of consensus) don't need to be voted upon in the DAO. In any case, a DAO submission should only be considered after considerable discussion on GitHub so that voters have context and reason to vote one way or another. Do not submit a DAO proposal before such discussion is established.
  
Format your proposal in Markdown. Make it a pleasure to read.
+
See [[Participating_in_a_DAO_voting_cycle|how to submit a proposal for DAO voting]].
  
In general, good proposals take time to research and write. Every minute you spend clearly and logically articulating your proposal is a minute that you save other contributors in understanding it. This diligence on your part will be appreciated and rewarded by others' attention. Cheaply written, "drive by" proposals that waste others' time will be closed immediately as ''was:incorrect''.
 
 
[[Category:Processes]]
 
[[Category:Processes]]

Latest revision as of 19:08, 22 January 2022

Proposals are a way to suggest significant project-wide changes or new initiatives where a broad consensus of contributors, users, and stakeholders is desired. Smaller changes to existing components, infrastructure, or processes are generally best discussed in other channels (on Matrix, other GitHub repositories, etc).

This article covers the roles, processes, and conventions for proposals.

Roles

Processes

Anyone may submit new proposals and/or review other proposals. But there are things you can do to make it more likely your ideas are received well.

Submission and Review

Research and Evaluate

Proposals are supposed to be significant items with enough weight to draw attention from core contributors, users, and stakeholders from across functions.

Note
If your idea is focused on a particular area of Bisq, it would be best to first float your idea in the channels for that area. For example, development-related ideas can be discussed in #dev on Matrix or in the main GitHub repository. Growth-related ideas can be discussed in #growth on Matrix or the growth GitHub repository.

Accordingly, proposals should be well-considered, well-researched, and well-articulated.

As a result, before submitting a proposal, please:

  1. Discuss your idea with other contributors to see if a proposal is worth submitting at all
  2. Search through existing proposals (both open and closed) to see whether something similar has already been proposed
  3. Notice which among those proposals have been accepted and rejected, and why
  4. Read this article to fully understand the proposal process and guidelines

Look through past proposals that succeeded to get a feel for how they were structured.

Create GitHub Issue

Once you've done research, floated your idea in the community in other channels, and think your idea might garner broader support, create a new GitHub issue in the repository on GitHub, written and formatted according to the following guidelines:

  • Write your proposal in a way that makes it as easy as possible to achieve rough consensus. This means that proposals should be as simple, focused, concrete and well-defined as possible. Your goal should be to make it as easy as possible for your fellow contributors to understand and agree with you.
  • Take full responsibility for your proposal. It is not the maintainers' job, nor anyone else’s, to see your proposal succeed. If people aren’t responding or reacting to your proposal, it’s your job to solicit that feedback more actively.
  • Never assume that anyone other than yourself is going to do the work described in your proposal. If your proposal does place expectations on other contributors, or requires them to change their behavior in any way, be explicit about that.
  • Provide context. Make a strong case for your proposal. Link to prior discussions. Do not make your reader do any more work than they have to to understand your proposal.
  • Format your proposal well. Make it a pleasure to read.

In general, good proposals take time to research and write. Every minute you spend clearly and logically articulating your proposal is a minute that you save other contributors in understanding it. This diligence on your part will be appreciated and rewarded by others' attention.

Warn
Cheaply-written, "drive by" proposals that waste others' time will be closed immediately as was:incorrect.

A maintainer will quickly review your proposal and will either (a) assign it to you to indicate your ownership and responsibility over it, or (b) close it and label it as was:incorrect if it does not follow the guidelines listed above.

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:

  • 👍: I agree with the proposal and want to see it enacted.
  • 😕: I am uncertain about the proposal and I need more information.
  • 👎: I disagree with the proposal and do not want to see it enacted.

Try to provide an explanation of your reaction, especially when reacting with a 😕 or 👎. If you don’t, then don’t expect your opinion to have much weight or get addressed.

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 Matrix or elsewhere and then summarize them back on the issue.

Evaluate

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.

After the two-week review period is over, a maintainer will evaluate reactions to and discussions about the proposal and will close the issue with a comment explaining that it is approved or rejected based on whether a rough consensus was achieved.

Approved proposals will be labeled with was:approved. Rejected proposals will be labeled with was:rejected.

If rough consensus has not been achieved, e.g. because discussion is still ongoing, dissenting concerns have not been addressed, or the proposal has turned out to be contentious, the maintainer will indicate that they cannot close the proposal, and that it is up to the submitter to take next steps to move the proposal forward. One option is to submit the proposal to the DAO for voting. If the proposal does not move forward after another two weeks, the maintainer will close and label it was:stalled.

If there have been no or very few reactions to a proposal after the two-week period, the maintainer will close it and label it as was:ignored.

Enact

Assuming your proposal was approved, the next step is to actually enact the changes described in that proposal, perhaps by creating a project or simply getting to work.

Submit to the DAO (if needed)

Sometimes it is necessary to submit proposals to the DAO for voting:

  • DAO parameter changes
  • proposal for bonded roles
  • contentious proposals for which there is strong interest but no clear consensus

For most general proposals this should not be necessary—general proposals that have clear consensus (or clear lack of consensus) don't need to be voted upon in the DAO. In any case, a DAO submission should only be considered after considerable discussion on GitHub so that voters have context and reason to vote one way or another. Do not submit a DAO proposal before such discussion is established.

See how to submit a proposal for DAO voting.