Skip to content

doc: deprecate Yay in favor of Yea

Nic Volanschi requested to merge nomadic-labs/tezos:nic@deprecate-yay-doc into master

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 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
Edited by Nic Volanschi

Merge request reports