diff --git a/docs/README.rst b/docs/README.rst index a550a07bc4da4fa967c1819cab4127156b82f4c2..8ee14ff16e40524154519071cec8cf2c651b0c17 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -82,9 +82,6 @@ Sphinx extensions Some ad-hoc reference kinds are supported. -- ``:package-src:`name``` or ``:package-src:`text``` points - to the gitlab source tree viewer where the `.opam` for the package - is located - ``:package:`name``` or ``:package:`text``` points to the ``odoc`` page of the package, checking that the page exists - ``:package-name:`name``` or ``:package-name:`text``` just diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index 6b972a00eb330ae4912c36cb8ae3fc0911fc4382..ae465af8ff855d2a9ddc052ab06a173c51248146 100644 --- a/docs/alpha/consensus.rst +++ b/docs/alpha/consensus.rst @@ -8,7 +8,7 @@ History ------- Before Tenderbake, there was -`Emmy* `_, +`Emmy* `_, a Nakamoto-style consensus consisting of a series of improvements of the one in the `Tezos whitepaper `_. @@ -434,6 +434,7 @@ Consensus related protocol parameters * - ``ENDORSING_REWARD_PER_SLOT`` - ``endorsing_reward / CONSENSUS_COMMITTEE_SIZE`` = 0.002857 tez +These are a subset of the :ref:`protocol constants `. .. _shell_proto_revisit_alpha: @@ -496,4 +497,4 @@ Further External Resources * Tenderbake `report `_ * Tenderbake `blog post `_. -* Tenderbake `tzip `_. +* Tenderbake `tzip `_. diff --git a/docs/alpha/proof_of_stake.rst b/docs/alpha/proof_of_stake.rst index a1fdef70dc020ca3b2d8f8eea252d547a091a01e..6f2a68e99ccff831a214a927cc68b5ea801d9332 100644 --- a/docs/alpha/proof_of_stake.rst +++ b/docs/alpha/proof_of_stake.rst @@ -147,7 +147,8 @@ The list of protocol constants can be found in the API of the `Constants module The values of protocol constants can be found using a :ref:`specific RPC call `, as shown in :ref:`this example `. -In particular, the protocol constants related to the proof-of-stake mechanism are detailed below. +In particular, the protocol constants related to the proof-of-stake mechanism are detailed :ref:`below `. +Other important subsystems of the protocol have their own list of protocol constants, such as the :ref:`consensus-related parameters ` and the :ref:`randomness generation parameters `. .. _ps_constants_alpha: diff --git a/docs/alpha/voting.rst b/docs/alpha/voting.rst index a8f38be8ef4933064e60a8f00a6cf0402c2c6aae..3d4dc8cf44af42fe2d048a2bf5ba0d1e05030a2c 100644 --- a/docs/alpha/voting.rst +++ b/docs/alpha/voting.rst @@ -127,15 +127,17 @@ The *vote participation* is the ratio of all the cumulated stake of cast ballots For the first vote, the *quorum* started at 80% of stake. The quorum is adjusted after each vote as detailed below. This adjustment is necessary to ensure that the amendment process can continue even if some delegates stop -participating. After each vote the new quorum is updated based on the old quorum -and the **vote participation** with the following coefficients:: +participating. After each vote the new quorum is updated based on the exponential moving average of the **vote participation**:: - new-quorum = 0.8 × old-quorum + 0.2 × participation + new_participation_ema = 0.8 * old_participation_ema + 0.2 * participation -However, in order to avoid establishing quorums close to 100% that would be +with the following formula:: + + new_quorum = 0.2 + (0.7 - 0.2) * old_participation_ema + +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 chronicle, the quorums are lower- and upper-bounded by -:ref:`quorum_caps`. +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. diff --git a/docs/developer/guidelines.rst b/docs/developer/guidelines.rst index 98f49f67fa98dcf6a222a74ef0c26a9e58579e43..2ef5c923b2b3c4f42cbd433cb0f1a8329b57539e 100644 --- a/docs/developer/guidelines.rst +++ b/docs/developer/guidelines.rst @@ -23,7 +23,9 @@ Note that: - Old source files may contain on the first line `Open Source License` instead of `MIT License`. When touching such a file, please replace the former with the latter, correct form. -For example, for a source file with multiple contributors spanning several years, the copyright lines may look as follows:: +For example, for a source file with multiple contributors spanning several years, the copyright lines may look as follows: + +.. code-block:: ocaml (* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. *) (* Copyright (c) 2019-2020 Nomadic Labs *) @@ -64,7 +66,9 @@ TODO/FIXME comments ~~~~~~~~~~~~~~~~~~~ During the :ref:`code review process `, follow-up issues may be created to improve some piece of code that already implement its specification (e.g., optimize, refactor, or bring a potentially useful generalization). -When the place of the future evolution is known in advance (e.g. a given function), you should mark it with a ``TODO`` comment of the form:: +When the place of the future evolution is known in advance (e.g. a given function), you should mark it with a ``TODO`` comment of the form: + +.. code-block:: ocaml (* TODO: @@ -149,15 +153,18 @@ Also at the level of the library, you should include a ``README.md`` in `Markdow Such files are mandatory in top-level directories of the Tezos codebase (such as ``src/`` and ``docs/``), and at least in immediate sub-directories of the source directory (``src/*/``). Because it is accessible only in the source tree, the file should contain information that might be of interest to the maintainers and contributors. -You must instantiate the ``README.md`` file with the following template:: +You must instantiate the ``README.md`` file with the following template: + +.. code-block:: markdown # Component Name ## API Documentation - + + + ## Installation + ## Overview