diff --git a/docs/011/voting.rst b/docs/011/voting.rst index accb0a3824642f3aacbebafe9f30dec30127ec3d..e9146ef7b6ef4a85b18a74a2a4b58cc1fcfe373e 100644 --- a/docs/011/voting.rst +++ b/docs/011/voting.rst @@ -19,7 +19,7 @@ Periods The amendment process consists of five *periods*. Each period lasts for 40960 blocks (5 cycles) (or approximately two weeks). The periods (listed below) -typically succeed one another for a total duration of approximately 2 months and +typically succeed one to another for a total duration of approximately 2 months and a half, after which the whole amendment process starts again. The five periods are as follows: @@ -27,7 +27,8 @@ The five periods are as follows: - *Proposal period*: During this period, delegates can - submit *protocol amendment proposals* (or, simply, *proposals*) using the - ``Proposals`` operation (see below). + ``Proposals`` operation (see below); + - upvote one or several proposals, using the same ``Proposals`` operation. Each delegate can submit a maximum of 20 proposals. Duplicates count towards this total. diff --git a/docs/012/voting.rst b/docs/012/voting.rst index d9a06e450997f52c7a6f987d5894bd79af864871..5b5cdf9252d6276bc9bcd2da61c87bae19ac5209 100644 --- a/docs/012/voting.rst +++ b/docs/012/voting.rst @@ -17,7 +17,7 @@ Periods The amendment process consists of five *periods*. Each period lasts for 40960 blocks (5 cycles) (or approximately two weeks). The periods (listed below) -typically succeed one another for a total duration of approximately 2 months and +typically succeed one to another for a total duration of approximately 2 months and a half, after which the whole amendment process starts again. The five periods are as follows: @@ -25,7 +25,8 @@ The five periods are as follows: - *Proposal period*: During this period, delegates can - submit *protocol amendment proposals* (or, simply, *proposals*) using the - ``Proposals`` operation (see below). + ``Proposals`` operation (see below); + - upvote one or several proposals, using the same ``Proposals`` operation. Each delegate can submit a maximum of 20 proposals. Duplicates count towards this total. diff --git a/docs/alpha/transaction_rollups.rst b/docs/alpha/transaction_rollups.rst index 18b6cf68c969b426a23672fe491184e9ffa58a43..7a1e23c9bc151ed5e79d919e40bccecf1bfb7b38 100644 --- a/docs/alpha/transaction_rollups.rst +++ b/docs/alpha/transaction_rollups.rst @@ -4,8 +4,8 @@ Transaction Rollups High-frequency transactions are hard to achieve in a blockchain that is decentralized and open. For this reason, many blockchains offer the possibility to define layer-2 solutions that relax some constraints in terms of consensus to -increase the transaction throughput. They relies on the layer-1 chain as a -gatekeeper and are optimistic that economic incentives are sufficient to prevent +increase the transaction throughput. Such solutions rely on the layer-1 chain as a +gatekeeper and are "optimistic" in that they consider that economic incentives are sufficient to prevent attacks. Introduction @@ -52,7 +52,7 @@ of optimistic rollups: share the whole tree, by means of Merkle proofs. Optimistic rollups implementations leverage these two properties. Firstly, -**rollup nodes** can submit **commitment** to the layer-1 chain, to advertise +**rollup nodes** can submit **commitments** to the layer-1 chain, to advertise the root hash of the **rollup context** after the application of a set of **rollup operations**. Secondly, **rollup participants** can assert the correctness of these **commitments**, and provide proofs asserting they are @@ -117,8 +117,7 @@ prefixed by ``tru1``. For instance, is a valid transaction rollup address. -When using the ``tezos-client`` to originate a transaction rollup, it outputs -the address. +When using the ``tezos-client`` to originate a transaction rollup, the client outputs +the address of the new rollup. -:: .. TODO: https://gitlab.com/tezos/tezos/-/issues/2154 diff --git a/docs/alpha/voting.rst b/docs/alpha/voting.rst index f102bf27bce30b6f1c79fdc56be8adfc08920716..0ba8fd6fe8a5d5cfcee489c6a5c8c8fbfac767a6 100644 --- a/docs/alpha/voting.rst +++ b/docs/alpha/voting.rst @@ -17,7 +17,7 @@ Periods The amendment process consists of five *periods*. Each period lasts for 40960 blocks (5 cycles) (or approximately two weeks). The periods (listed below) -typically succeed one another for a total duration of approximately 2 months and +typically succeed one to another for a total duration of approximately 2 months and a half, after which the whole amendment process starts again. The five periods are as follows: @@ -25,7 +25,8 @@ The five periods are as follows: - *Proposal period*: During this period, delegates can - submit *protocol amendment proposals* (or, simply, *proposals*) using the - ``Proposals`` operation (see below). + ``Proposals`` operation (see below); + - upvote one or several proposals, using the same ``Proposals`` operation. Each delegate can submit a maximum of 20 proposals. Duplicates count towards this total. diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index 4671ae2739aff68c4d054553e33f1e988b3321f1..051cfcc5a52b2cac5b6ef139c99f3a89e80ae6cd 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -32,6 +32,7 @@ You may also want to fix some typos and minor errors or incoherencies in the *do This kind of small contributions can be done without creating a merge request, by directly pushing commits to the ``typo-doc`` branch, which is regularly merged into the master branch, e.g., every one or two weeks. This periodic merging is implemented by a series of MRs named "the typo train", created for you by a volunteer, and batching the currently pending fixes. Of course, all these commits will be reviewed before being integrated. +The current edition of the typo train MR can be found in meta-issue :gl:`#2329`. To directly contribute to the *codebase*, expertise in a few areas is necessary. @@ -354,7 +355,7 @@ must be mitigated as follows: - Have the entire piece of work described or done somewhere. For example in an issue, or a branch containing the entire change, or a large (unsplit) work as a draft merge request. - For complex works, an external document may be referred in the issue/MR, detailing the design/implementation rationale; if such documents are only targeted to reviewers and/or are only describing a *change*, they should not go in the online documentation. + For complex works, an external document may be referred in the issue/MR, detailing the design/implementation rationale; if such documents are only targeted to reviewers and/or are only describing a *change*, they should not go in the online documentation. - Include a link to the entire piece of work in the description of each small merge requests created by splitting the large piece of work. This will help reviewers get the big picture. diff --git a/docs/developer/error_monad.rst b/docs/developer/error_monad.rst index 868b991c70c25112e574493beeec665fb84b5ee1..d45a77eb8d510e7753f7dae7e15527224ad8d181 100644 --- a/docs/developer/error_monad.rst +++ b/docs/developer/error_monad.rst @@ -261,7 +261,7 @@ are the same (``'e``): val ( let* ) : ('a, 'e) result -> ('a -> ('b, 'e) result) -> ('b, 'e) result When you need to mix those function, you have to either handle the -errors of each idependently (see the section above about recovering from +errors of each independently (see the section above about recovering from errors) or you need to convert the errors so they have the same type. You should use ``Result.map_error`` to do that. @@ -768,7 +768,7 @@ dedicated to binding Result-only expressions. .. sidebar:: Mnemonic The ``let*?`` binding operator uses the question mark (``?``) to represent - the uncertainty of the ``result``. Is it a sucess? Is it a failure? + the uncertainty of the ``result``. Is it a success? Is it a failure? From Lwt-only into Lwt-``result`` @@ -786,10 +786,10 @@ dedicated to binding Lwt-only expressions. .. sidebar:: Mnemonic The ``let*!`` binding operator uses the exclamation mark (``!``) to represent - the impossibilty of errors: Thou shall not fail! + the impossibility of errors: Thou shall not fail! -Wait! there is too much! what module am I supposed to open locally and what operators should I use? +Wait! There is too much! What module am I supposed to open locally and what operators should I use? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you are feeling overwhelmed by the different syntax modules, here are @@ -993,10 +993,10 @@ the errors to a common type. You can also use the ``Result.map_error`` and ``lwt_map_error`` functions introduced in previous sections. -Wait! it was supposed to be “one single uniform way of dealing with errors”! what is this? +Wait! It was supposed to be “one single uniform way of dealing with errors”! What is this? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The error management in Octez is through a unified way (syntax modules +The error management in Octez is a unified way (syntax modules with regular, predictable interfaces) of handling different types of errors. @@ -1098,7 +1098,7 @@ They do not even require the syntax modules to be open. in retry original_limit f - You can use all the formating percent-escapes from the `Format + You can use all the formatting percent-escapes from the `Format module `__. However, you should generally keep the message on a single line so that it can be printed nicely in logs. @@ -1216,7 +1216,7 @@ in the shell, just use :literal:`\`Temporary`. - ``description``: a longer human readable string. - ``pp``: a pretty-printing function carrying enough information for a full error message for the user. Note that the function does not receive the error, - instead it receives the *projected payload of the error* (here a 3-uple + instead it receives the *projected payload of the error* (here a 3-tuple ``(expected, got, line)``. - encoding: an encoding for the projected payload of the error. - projection: a partial function that matches the specific error @@ -2144,9 +2144,9 @@ E.g., Haskell relies heavily on monads and has the dedicated let add x y = let ( let* ) = OptionMonad.bind in - let* x = int_of_strin_opt x in - let* y = int_of_strin_opt y in - Some (strin_of_int (x + y)) + let* x = int_of_string_opt x in + let* y = int_of_string_opt y in + Some (string_of_int (x + y)) - `infix operators `__ @@ -2155,9 +2155,9 @@ E.g., Haskell relies heavily on monads and has the dedicated let add x y = let ( >>= ) = OptionMonad.bind in - int_of_strin_opt x >>= fun x -> - int_of_strin_opt y >>= fun y -> - Some (strin_of_int (x + y)) + int_of_string_opt x >>= fun x -> + int_of_string_opt y >>= fun y -> + Some (string_of_int (x + y)) Note that mixing multiple infix operators is not always easy because of precedence and associativity. @@ -2167,9 +2167,9 @@ E.g., Haskell relies heavily on monads and has the dedicated :: let add x y = - OptionMonad.bind (int_of_strin_opt x) @@ fun x -> - OptionMonad.bind (int_of_strin_opt y) @@ fun y -> - Some (strin_of_int (x + y)) + OptionMonad.bind (int_of_string_opt x) @@ fun x -> + OptionMonad.bind (int_of_string_opt y) @@ fun y -> + Some (string_of_int (x + y)) This is useful for the occasional application: you do not need to declare a dedicated operator nor open a dedicated syntax module. @@ -2181,7 +2181,7 @@ In depth discussion: ``Error_monad``, ``src/lib_error_monad/``, ``Tezos_base__Tz ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The different parts of the error monad (syntax modules, extended stdlib, -tracing promitives, etc.) are defined in separate files. Yet, they are +tracing primitives, etc.) are defined in separate files. Yet, they are all available to you directly. This section explains where each part is defined and how it reaches the scope of your code. diff --git a/docs/developer/time_measurement_ppx.rst b/docs/developer/time_measurement_ppx.rst index c5086f87ea4e6c063c6337787d0c87475e340ec7..7690ec1fd4c40a76143ba28a8136cee72f85e68b 100644 --- a/docs/developer/time_measurement_ppx.rst +++ b/docs/developer/time_measurement_ppx.rst @@ -1,17 +1,17 @@ Time measurement PPX ==================== -The time measurement PPX is an Ocaml preprocessing tool that intends to -embed generated benchmark tooling into specific pieces of Ocaml code. +The time measurement PPX is an OCaml preprocessing tool that intends to +embed generated benchmark tooling into specific pieces of OCaml code. -It is able to measure the time spent in the execution of annotated Ocaml +It is able to measure the time spent in the execution of annotated OCaml expressions and to log these measurements when desired. Since it uses ``Tezos_event_logging`` for the logging part, this PPX can easily be used together with ``Tezt`` framework to perform the benchmarking of specific parts of Tezos node. **This PPX is only intended to be used for tests. As the current runtime -implemetation performs memory allocation, an unwise usage could mess with +implementation performs memory allocation, an unwise usage could mess with the garbage collector or blow up your memory.** **PLEASE, MAKE SURE THAT IT IS NOT ACTIVATED WHEN COMPILING CODE FOR @@ -21,9 +21,9 @@ Getting started --------------- Suppose we want to measure the performance of some specific parts of -the following Ocaml function inside the module ``lib_my_module``: +the following OCaml function inside the module ``lib_my_module``: -.. code-block:: Ocaml +.. code-block:: OCaml let my_function () = let a = f () in @@ -40,10 +40,10 @@ Suppose also that module ``lib_my_module`` contains the following dune file: (libraries lwt) (flags (:standard -open Lwt))) -We can mesure the execution time of ``f ()`` and ``g ()`` and log them by -adding the following Ocaml attributes: +We can measure the execution time of ``f ()`` and ``g ()`` and log them by +adding the following OCaml attributes: -.. code-block:: Ocaml +.. code-block:: OCaml let my_function () = let a = f () [@time.duration f_time] in @@ -51,13 +51,13 @@ adding the following Ocaml attributes: h () >>= fun c -> foo a b c [@time.flush] -``[@time.duration]`` will be used to mesure the time of ``f ()`` and ``g ()`` +``[@time.duration]`` will be used to measure the time of ``f ()`` and ``g ()`` expressions execution and to name them respectively ``f_time`` and ``g_time``. ``[@time.flush]`` will then be used to log these measurements. -When the preprocessig will occur, the code will be transform as follows: +When the preprocessing will occur, the code will be transformed as follows: -.. code-block:: Ocaml +.. code-block:: OCaml let my_function () = let a = Tezos_time_measurement_runtime.Default.Time_measurement.duration @@ -81,7 +81,7 @@ The resulting thunk is passed to the function ``Time_measurement.duration`` from the module ``Tezos_time_measurement_runtime.Default`` along with the argument ``("f_time", [])``. -``Time_measurement.duration`` mesures the current time before and after executing +``Time_measurement.duration`` measures the current time before and after executing the given thunk in order to compute the span between the two timestamps. The resulting measurement is then bufferized in memory and, at last, the function evaluates in the result of the thunk so that we can respect the invariants of the initial program. @@ -110,11 +110,11 @@ and also removes them from memory. The flushing promise is then bounded again to return ``__flush__id__0`` value to preserve the program invariants as well. -That's great, but since Ocaml attributes are ignored by default, +That's great, but since OCaml attributes are ignored by default, we still need to update the dune stanza of ``lib_my_module`` so that it can take effect: -.. code-block:: Ocaml +.. code-block:: OCaml (library (name tezos_my_module) @@ -124,11 +124,11 @@ it can take effect: This update adds the ``tezos-time-measurement`` instrumentation backend, which, if set using ``--instrument-with tezos-time-measurement`` on ``dune build`` -command line, will preprocess our Ocaml code using the PPX. +command line, will preprocess our OCaml code using the PPX. This is useful to prevent our code from embedding benchmarking tooling in production by mistake: If no backend is specified for the compilation, added -attributes will just be ignored by the Ocaml compiler and that's it! +attributes will just be ignored by the OCaml compiler and that's it! We can now compile our ready-to-benchmark code::: @@ -146,18 +146,18 @@ is displayed on standard output. For example: Aug 23 17:52:58.593 - benchmarking: time measurements: Aug 23 17:52:58.593 - benchmarking: [(f_time, 0.000177); (g_time, 0.005658)] -Compatible Ocaml Attributes +Compatible OCaml Attributes --------------------------- The PPX provides the handling of three attributes: - ``[@time.duration