diff --git a/docs/CHANGES.rst b/docs/CHANGES.rst index 996bade8055f2a977dad4e2ab5dbb16f774c14a1..fb3b07df8dad7f26be4f17d7811bdaf4c04f67fe 100644 --- a/docs/CHANGES.rst +++ b/docs/CHANGES.rst @@ -58,6 +58,9 @@ Node - Replaced some "precheck" occurrences with "validate" in event and error identifiers and messages. (MR :gl: `!7513`) +- Document the usage of "Yay" as a deprecated synonym for "Yea", to encourage + using the correct value in the future. (MR :gl:`!7960`) + Baker ----- diff --git a/docs/alpha/blocks_ops.rst b/docs/alpha/blocks_ops.rst index 667006548aa7e49364f0d40743d228ee1579741d..7968024ee1a46175bf9b5c4b9b4afb6a70919604 100644 --- a/docs/alpha/blocks_ops.rst +++ b/docs/alpha/blocks_ops.rst @@ -82,7 +82,7 @@ voting operations: - The ``Ballot`` operation enables delegates to participate in the Exploration and Promotion periods. Delegates use this operation to - vote for (``Yay``), against (``Nay``), or to side with the majority + vote for (``Yea``), against (``Nay``), or to side with the majority (``Pass``), when examining a protocol amendment proposal. Further details on each operation's implementation and semantics are diff --git a/docs/alpha/voting.rst b/docs/alpha/voting.rst index 133f29952a79d87919fc33281b092e6ba9e062c9..44e8331d6e71ea928976bf3a0f013887f92e9147 100644 --- a/docs/alpha/voting.rst +++ b/docs/alpha/voting.rst @@ -44,11 +44,11 @@ The five periods are as follows: moves back to a new **proposal period**. - *Exploration period*: During this period delegates can cast one - Yay, Nay, or Pass ballot on the selected proposal. They do so using the + Yea, Nay, or Pass ballot on the selected proposal. They do so using the ``Ballot`` operation. If the voting participation reaches *quorum* and there is a *super-majority* - of Yay, the process moves to the **cooldown period**. (See below for details + of Yea, the process moves to the **cooldown period**. (See below for details on participation, quorum, and super-majority.) Otherwise the process moves back to the **proposal period**. @@ -60,11 +60,11 @@ The five periods are as follows: At the end of this period, the process moves to the **promotion period**. -- *Promotion period*: During this period, delegates can cast a Yay, Nay, or Pass +- *Promotion period*: During this period, delegates can cast a Yea, Nay, or Pass ballots using the ``Ballot`` operation. If the voting participation reaches *quorum* and there is a super-majority of - Yay, the process moves to the **adoption period**. + Yea, the process moves to the **adoption period**. Otherwise the process moves back to the **proposal period**. @@ -83,6 +83,9 @@ The five periods are as follows: And a new **proposal period** starts. +.. warning:: + Thanks to an old spelling mistake, the most enthusiastic voters can cast ``Yay`` ballots. Enthusiasm does however not impact the result of the vote and the tools accepting ``Yay`` consider it as a deprecated synonym for ``Yea``. + Activation ---------- @@ -101,7 +104,7 @@ requirement might differ, etc. Voting Power ------------ -When supporting a proposal or casting a Yay, Nay, or Pass ballot, each delegate +When supporting a proposal or casting a Yea, Nay, or Pass ballot, each delegate has a voting power equal to its *stake*. More precisely, the voting power of a delegate during a voting period is its :ref:`staking balance `, measured in *mutez*, sampled at the beginning of the period. (Note that this is opposed to validator selection for consensus, which is based on the active stake, and sampled at some stake snapshot during some previous cycle.) @@ -110,12 +113,12 @@ Super-majority and Quorum As mentioned above, during either of the **exploration** or **promotion** periods, delegates can cast ballots using the ``Ballot`` operation (see below). -In both cases, delegates can cast a single Yay, Nay, or Pass ballot. A ballot +In both cases, delegates can cast a single Yea, Nay, or Pass ballot. A ballot has a weight equal to the delegate's stake as detailed above. For either of these two periods, the process continues to the next period if the *vote participation* reaches *quorum* and there is a *super-majority* of -Yay. +Yea. The *vote participation* is the ratio of all the cumulated stake of cast ballots (including Pass ballots) to the total stake. @@ -135,8 +138,8 @@ This formula avoids establishing quorums close to 100% that would be very difficult to attain, or, conversely, low quorums close to 0% making little participation chronic, ensuring that the quorums are lower- and upper-bounded by :ref:`quorum_caps` (0.2 and 0.7, respectively). -The *super-majority* is reached if the cumulated stake of Yay ballots is -greater than 8/10 of the cumulated stake of Yay and Nay ballots. +The *super-majority* is reached if the cumulated stake of Yea ballots is +greater than 8/10 of the cumulated stake of Yea and Nay ballots. Note that Pass ballots do not count towards or against the super-majority; they still counts towards participation and quorum. @@ -232,7 +235,7 @@ A *ballot* operation can only be submitted during periods where a vote happens ballot: Vote_repr.ballot ; } The fields ``source`` and ``period`` are the same as above, while ``proposal`` -is the currently selected proposal and ``ballot`` is one of ``Yay``, ``Nay`` or +is the currently selected proposal and ``ballot`` is one of ``Yea``, ``Nay`` or ``Pass``. The ``Pass`` vote allows a delegate to contribute towards the quorum without contributing towards the super-majority. This is important because, as detailed @@ -319,7 +322,7 @@ Submit ballots During either of the **exploration** or **promotion** periods, ballots can be submitted once with:: - octez-client submit ballot for + octez-client submit ballot for Further External Resources -------------------------- diff --git a/docs/mumbai/blocks_ops.rst b/docs/mumbai/blocks_ops.rst index cfc3e4d7663a915551399a3b1cecc4012192e1f5..6d28fdc0fb85ca0e577500c9557c010b6e4c75c3 100644 --- a/docs/mumbai/blocks_ops.rst +++ b/docs/mumbai/blocks_ops.rst @@ -85,7 +85,7 @@ voting operations: - The ``Ballot`` operation enables delegates to participate in the Exploration and Promotion periods. Delegates use this operation to - vote for (``Yay``), against (``Nay``), or to side with the majority + vote for (``Yea``), against (``Nay``), or to side with the majority (``Pass``), when examining a protocol amendment proposal. Further details on each operation's implementation and semantics are diff --git a/docs/mumbai/voting.rst b/docs/mumbai/voting.rst index 874b8f69ed44bbca6148bec20050ff646e6e3e95..2ab48d015a4d5e2e772e983a7d3d7843feb17725 100644 --- a/docs/mumbai/voting.rst +++ b/docs/mumbai/voting.rst @@ -44,11 +44,11 @@ The five periods are as follows: moves back to a new **proposal period**. - *Exploration period*: During this period delegates can cast one - Yay, Nay, or Pass ballot on the selected proposal. They do so using the + Yea, Nay, or Pass ballot on the selected proposal. They do so using the ``Ballot`` operation. If the voting participation reaches *quorum* and there is a *super-majority* - of Yay, the process moves to the **cooldown period**. (See below for details + of Yea, the process moves to the **cooldown period**. (See below for details on participation, quorum, and super-majority.) Otherwise the process moves back to the **proposal period**. @@ -60,11 +60,11 @@ The five periods are as follows: At the end of this period, the process moves to the **promotion period**. -- *Promotion period*: During this period, delegates can cast a Yay, Nay, or Pass +- *Promotion period*: During this period, delegates can cast a Yea, Nay, or Pass ballots using the ``Ballot`` operation. If the voting participation reaches *quorum* and there is a super-majority of - Yay, the process moves to the **adoption period**. + Yea, the process moves to the **adoption period**. Otherwise the process moves back to the **proposal period**. @@ -83,6 +83,9 @@ The five periods are as follows: And a new **proposal period** starts. +.. warning:: + Thanks to an old spelling mistake, the most enthusiastic voters can cast ``Yay`` ballots. Enthusiasm does however not impact the result of the vote and the tools accepting ``Yay`` consider it as a deprecated synonym for ``Yea``. + Activation ---------- @@ -101,7 +104,7 @@ requirement might differ, etc. Voting Power ------------ -When supporting a proposal or casting a Yay, Nay, or Pass ballot, each delegate +When supporting a proposal or casting a Yea, Nay, or Pass ballot, each delegate has a voting power equal to its *stake*. More precisely, the voting power of a delegate during a voting period is its :ref:`staking balance `, measured in *mutez*, sampled at the beginning of the period. (Note that this is opposed to validator selection for consensus, which is based on the active stake, and sampled at some stake snapshot during some previous cycle.) Super-majority and Quorum @@ -109,12 +112,12 @@ Super-majority and Quorum As mentioned above, during either of the **exploration** or **promotion** periods, delegates can cast ballots using the ``Ballot`` operation (see below). -In both cases, delegates can cast a single Yay, Nay, or Pass ballot. A ballot +In both cases, delegates can cast a single Yea, Nay, or Pass ballot. A ballot has a weight equal to the delegate's stake as detailed above. For either of these two periods, the process continues to the next period if the *vote participation* reaches *quorum* and there is a *super-majority* of -Yay. +Yea. The *vote participation* is the ratio of all the cumulated stake of cast ballots (including Pass ballots) to the total stake. @@ -134,8 +137,8 @@ This formula avoids establishing quorums close to 100% that would be very difficult to attain, or, conversely, low quorums close to 0% making little participation chronic, ensuring that the quorums are lower- and upper-bounded by :ref:`quorum_caps` (0.2 and 0.7, respectively). -The *super-majority* is reached if the cumulated stake of Yay ballots is -greater than 8/10 of the cumulated stake of Yay and Nay ballots. +The *super-majority* is reached if the cumulated stake of Yea ballots is +greater than 8/10 of the cumulated stake of Yea and Nay ballots. Note that Pass ballots do not count towards or against the super-majority; they still counts towards participation and quorum. @@ -231,7 +234,7 @@ A *ballot* operation can only be submitted during periods where a vote happens ballot: Vote_repr.ballot ; } The fields ``source`` and ``period`` are the same as above, while ``proposal`` -is the currently selected proposal and ``ballot`` is one of ``Yay``, ``Nay`` or +is the currently selected proposal and ``ballot`` is one of ``Yea``, ``Nay`` or ``Pass``. The ``Pass`` vote allows a delegate to contribute towards the quorum without contributing towards the super-majority. This is important because, as detailed @@ -318,7 +321,7 @@ Submit ballots During either of the **exploration** or **promotion** periods, ballots can be submitted once with:: - octez-client submit ballot for + octez-client submit ballot for Further External Resources -------------------------- diff --git a/docs/nairobi/blocks_ops.rst b/docs/nairobi/blocks_ops.rst index 5b80d5c774dbe44ebf40b157427ac136d93a0aa3..fcc74e701fd10f757b12c9fcece0e9122a6821e4 100644 --- a/docs/nairobi/blocks_ops.rst +++ b/docs/nairobi/blocks_ops.rst @@ -82,7 +82,7 @@ voting operations: - The ``Ballot`` operation enables delegates to participate in the Exploration and Promotion periods. Delegates use this operation to - vote for (``Yay``), against (``Nay``), or to side with the majority + vote for (``Yea``), against (``Nay``), or to side with the majority (``Pass``), when examining a protocol amendment proposal. Further details on each operation's implementation and semantics are diff --git a/docs/nairobi/voting.rst b/docs/nairobi/voting.rst index 3dd7895db76443946a76dbb4a200bae6c5b0c009..46a6056566303de38fe2f5932b4aba3a47ef8014 100644 --- a/docs/nairobi/voting.rst +++ b/docs/nairobi/voting.rst @@ -44,11 +44,11 @@ The five periods are as follows: moves back to a new **proposal period**. - *Exploration period*: During this period delegates can cast one - Yay, Nay, or Pass ballot on the selected proposal. They do so using the + Yea, Nay, or Pass ballot on the selected proposal. They do so using the ``Ballot`` operation. If the voting participation reaches *quorum* and there is a *super-majority* - of Yay, the process moves to the **cooldown period**. (See below for details + of Yea, the process moves to the **cooldown period**. (See below for details on participation, quorum, and super-majority.) Otherwise the process moves back to the **proposal period**. @@ -60,11 +60,11 @@ The five periods are as follows: At the end of this period, the process moves to the **promotion period**. -- *Promotion period*: During this period, delegates can cast a Yay, Nay, or Pass +- *Promotion period*: During this period, delegates can cast a Yea, Nay, or Pass ballots using the ``Ballot`` operation. If the voting participation reaches *quorum* and there is a super-majority of - Yay, the process moves to the **adoption period**. + Yea, the process moves to the **adoption period**. Otherwise the process moves back to the **proposal period**. @@ -83,6 +83,9 @@ The five periods are as follows: And a new **proposal period** starts. +.. warning:: + Thanks to an old spelling mistake, the most enthusiastic voters can cast ``Yay`` ballots. Enthusiasm does however not impact the result of the vote and the tools accepting ``Yay`` consider it as a deprecated synonym for ``Yea``. + Activation ---------- @@ -101,7 +104,7 @@ requirement might differ, etc. Voting Power ------------ -When supporting a proposal or casting a Yay, Nay, or Pass ballot, each delegate +When supporting a proposal or casting a Yea, Nay, or Pass ballot, each delegate has a voting power equal to its *stake*. More precisely, the voting power of a delegate during a voting period is its :ref:`staking balance `, measured in *mutez*, sampled at the beginning of the period. (Note that this is opposed to validator selection for consensus, which is based on the active stake, and sampled at some stake snapshot during some previous cycle.) @@ -110,12 +113,12 @@ Super-majority and Quorum As mentioned above, during either of the **exploration** or **promotion** periods, delegates can cast ballots using the ``Ballot`` operation (see below). -In both cases, delegates can cast a single Yay, Nay, or Pass ballot. A ballot +In both cases, delegates can cast a single Yea, Nay, or Pass ballot. A ballot has a weight equal to the delegate's stake as detailed above. For either of these two periods, the process continues to the next period if the *vote participation* reaches *quorum* and there is a *super-majority* of -Yay. +Yea. The *vote participation* is the ratio of all the cumulated stake of cast ballots (including Pass ballots) to the total stake. @@ -135,8 +138,8 @@ This formula avoids establishing quorums close to 100% that would be very difficult to attain, or, conversely, low quorums close to 0% making little participation chronic, ensuring that the quorums are lower- and upper-bounded by :ref:`quorum_caps` (0.2 and 0.7, respectively). -The *super-majority* is reached if the cumulated stake of Yay ballots is -greater than 8/10 of the cumulated stake of Yay and Nay ballots. +The *super-majority* is reached if the cumulated stake of Yea ballots is +greater than 8/10 of the cumulated stake of Yea and Nay ballots. Note that Pass ballots do not count towards or against the super-majority; they still counts towards participation and quorum. @@ -232,7 +235,7 @@ A *ballot* operation can only be submitted during periods where a vote happens ballot: Vote_repr.ballot ; } The fields ``source`` and ``period`` are the same as above, while ``proposal`` -is the currently selected proposal and ``ballot`` is one of ``Yay``, ``Nay`` or +is the currently selected proposal and ``ballot`` is one of ``Yea``, ``Nay`` or ``Pass``. The ``Pass`` vote allows a delegate to contribute towards the quorum without contributing towards the super-majority. This is important because, as detailed @@ -319,7 +322,7 @@ Submit ballots During either of the **exploration** or **promotion** periods, ballots can be submitted once with:: - octez-client submit ballot for + octez-client submit ballot for Further External Resources -------------------------- diff --git a/src/proto_016_PtMumbai/lib_client_commands/client_proto_context_commands.ml b/src/proto_016_PtMumbai/lib_client_commands/client_proto_context_commands.ml index 632bda85d7c6a838bc18ad7fbceae5d5a1e6a5c9..51d4dc7637d031f33c3061c600735c1c8b3fc36f 100644 --- a/src/proto_016_PtMumbai/lib_client_commands/client_proto_context_commands.ml +++ b/src/proto_016_PtMumbai/lib_client_commands/client_proto_context_commands.ml @@ -2344,7 +2344,9 @@ let commands_rw () = | Some hash -> Lwt_result_syntax.return hash)) @@ param ~name:"ballot" - ~desc:"the ballot value (yea/yay, nay, or pass)" + ~desc: + "the ballot value (yea, nay, or pass; yay is a deprecated synonym \ + for yea)" (parameter ~autocomplete:(fun _ -> Lwt_result_syntax.return ["yea"; "nay"; "pass"]) diff --git a/src/proto_017_PtNairob/lib_client_commands/client_proto_context_commands.ml b/src/proto_017_PtNairob/lib_client_commands/client_proto_context_commands.ml index 9070a0e6d51bdb9c93711226f14d8314ccc75964..bade4e8008d115e707c0f9f81ff402902925957b 100644 --- a/src/proto_017_PtNairob/lib_client_commands/client_proto_context_commands.ml +++ b/src/proto_017_PtNairob/lib_client_commands/client_proto_context_commands.ml @@ -2312,7 +2312,9 @@ let commands_rw () = | Some hash -> Lwt_result_syntax.return hash)) @@ param ~name:"ballot" - ~desc:"the ballot value (yea/yay, nay, or pass)" + ~desc: + "the ballot value (yea, nay, or pass; yay is a deprecated synonym \ + for yea)" (parameter ~autocomplete:(fun _ -> Lwt_result_syntax.return ["yea"; "nay"; "pass"]) diff --git a/src/proto_alpha/lib_client_commands/client_proto_context_commands.ml b/src/proto_alpha/lib_client_commands/client_proto_context_commands.ml index 8cf068355c23bdaf32d388eed30294610c10602a..328071aba4d67d9d1e8beaa8137a383c728667db 100644 --- a/src/proto_alpha/lib_client_commands/client_proto_context_commands.ml +++ b/src/proto_alpha/lib_client_commands/client_proto_context_commands.ml @@ -2334,7 +2334,9 @@ let commands_rw () = | Some hash -> Lwt_result_syntax.return hash)) @@ param ~name:"ballot" - ~desc:"the ballot value (yea/yay, nay, or pass)" + ~desc: + "the ballot value (yea, nay, or pass; yay is a deprecated synonym \ + for yea)" (parameter ~autocomplete:(fun _ -> Lwt_result_syntax.return ["yea"; "nay"; "pass"])