From d7727691cbf4570c9c32918fc5e2b6bec61adc12 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 9 Mar 2023 10:32:12 +0100 Subject: [PATCH 1/4] doc: deprecate Yay in the doc --- docs/alpha/blocks_ops.rst | 2 +- docs/alpha/voting.rst | 25 ++++++++++++++----------- 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/docs/alpha/blocks_ops.rst b/docs/alpha/blocks_ops.rst index 667006548aa7..7968024ee1a4 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 133f29952a79..44e8331d6e71 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 -------------------------- -- GitLab From 1a153f0c92b07e5dbfddf7008a556b3c5532ad38 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 9 Mar 2023 10:36:22 +0100 Subject: [PATCH 2/4] doc: deprecate Yay in generated doc --- .../lib_client_commands/client_proto_context_commands.ml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 8cf068355c23..328071aba4d6 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"]) -- GitLab From cacc94d68a313d005baa7abe2f0de8ebbae9d79c Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 31 Mar 2023 17:02:02 +0200 Subject: [PATCH 3/4] doc: add changelog item for Yea/Yay --- docs/CHANGES.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/CHANGES.rst b/docs/CHANGES.rst index 996bade8055f..fb3b07df8dad 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 ----- -- GitLab From c3e90794097f097f046d95af655fa4a656ab48ab Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 13 Apr 2023 15:26:52 +0200 Subject: [PATCH 4/4] doc: backport changes to Mumbai and Nairobi --- docs/mumbai/blocks_ops.rst | 2 +- docs/mumbai/voting.rst | 25 +++++++++++-------- docs/nairobi/blocks_ops.rst | 2 +- docs/nairobi/voting.rst | 25 +++++++++++-------- .../client_proto_context_commands.ml | 4 ++- .../client_proto_context_commands.ml | 4 ++- 6 files changed, 36 insertions(+), 26 deletions(-) diff --git a/docs/mumbai/blocks_ops.rst b/docs/mumbai/blocks_ops.rst index cfc3e4d7663a..6d28fdc0fb85 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 874b8f69ed44..2ab48d015a4d 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 5b80d5c774db..fcc74e701fd1 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 3dd7895db764..46a605656630 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 632bda85d7c6..51d4dc7637d0 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 9070a0e6d51b..bade4e8008d1 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"]) -- GitLab