doc: deprecate Yay in favor of Yea
Context
Addresses issue #4251.
Official voting systems use Yea/Nay (see https://en.wikipedia.org/wiki/Voting_methods_in_deliberative_assemblies), or sometimes Aye/Nay in voice voting (see https://en.wikipedia.org/wiki/Voice_vote). To the best of my knowledge, the word Yay
is never accepted in any state voting system around the world.
For historical reasons tracing back to the original Tezos white paper, the Tezos protocol voting procedure and documentation rather uses the incorrect form Yay instead of Yea. Although most Tezos tools tend to accept both Yay and Yea, the former is much more present in the doc, in the RPC API, and in official communications. For example:
- the page presenting the Tezos voting system mentions Yay 12 times, and never mentions Yea (see https://tezos.gitlab.io/mumbai/voting.html)
- the last communication on the Mumbai protocol patch only mentions Yay but not Yea (see https://research-development.nomadic-labs.com/mumbai2-announcement.html)
- the RPC API mentions Yay 17 times and never Yea (see https://tezos.gitlab.io/_sources/mumbai/rpc.rst.txt)
The problem in not a minor one (as it may seem at first sight to developers) because:
- The on-chain voting procedure is one of the flagship features of Tezos
- Voting concerns not just tools, but the whole community of Tezos users, who are participating or at least following protocol votes about every three months
- This community of users is expected to increase by a significant factor during this year or so, hence the problem may only become more relevant.
While acknowledging the fact that changing the habits and the tools is difficult, this MR proposes to reverse the trend towards the correct form Yea, and deprecating the incorrect form Yay.
The changes are deliberately split in several layers, with increasing ambition:
- fixing the manually-written documentation
- fixing the automatically-generating documentation
-
fixing user-facing tool output such as poll reports(moved to !8234 (closed)) -
(optionally) fixing the encoding and/or RPC API(moved to !8234 (closed))
Manually testing the MR
Check that the new documentation and user-facing reports favor the right form (Yea).
Check that the tests are not broken by the tool output changes and/or RPC API changes, if any.
Checklist
-
Document the interface of any function added or modified (see the coding guidelines) -
Document any change to the user interface, including configuration parameters (see node configuration) -
Provide automatic testing (see the testing guide). -
For new features and bug fixes, add an item in the appropriate changelog ( docs/protocols/alpha.rst
for the protocol and the environment,CHANGES.rst
at the root of the repository for everything else). -
Select suitable reviewers using the Reviewers
field below. -
Select as Assignee
the next person who should take action on that MR