From 6232b1ccf196f3fa58de335166db3bcc37c7d03b Mon Sep 17 00:00:00 2001 From: Eugen Zalinescu Date: Mon, 10 Oct 2022 17:33:21 +0200 Subject: [PATCH 1/7] proto: add doc string for Consensus_key module --- src/proto_alpha/lib_protocol/alpha_context.mli | 3 ++- src/proto_alpha/lib_protocol/delegate_consensus_key.mli | 6 ++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/src/proto_alpha/lib_protocol/alpha_context.mli b/src/proto_alpha/lib_protocol/alpha_context.mli index 18a61fc944b2..f905bf8b2d85 100644 --- a/src/proto_alpha/lib_protocol/alpha_context.mli +++ b/src/proto_alpha/lib_protocol/alpha_context.mli @@ -2486,6 +2486,7 @@ module Receipt : sig val group_balance_updates : balance_updates -> balance_updates tzresult end +(** This module re-exports definitions from {!Delegate_consensus_key}. *) module Consensus_key : sig type pk = { delegate : Signature.Public_key_hash.t; @@ -2506,7 +2507,7 @@ module Consensus_key : sig end (** This module re-exports definitions from {!Delegate_storage}, - {!Delegate_missed_endorsements_storage}, + {!Delegate_consensus_key}, {!Delegate_missed_endorsements_storage}, {!Delegate_slashed_deposits_storage}, {!Delegate_cycles}. *) module Delegate : sig val frozen_deposits_limit : diff --git a/src/proto_alpha/lib_protocol/delegate_consensus_key.mli b/src/proto_alpha/lib_protocol/delegate_consensus_key.mli index babfeb0349e1..edbf190c8039 100644 --- a/src/proto_alpha/lib_protocol/delegate_consensus_key.mli +++ b/src/proto_alpha/lib_protocol/delegate_consensus_key.mli @@ -23,6 +23,12 @@ (* *) (*****************************************************************************) +(** Management of a delegate's consensus key, the one used to sign + blocks and consensus operations. It is responsible for maintaining + the tables {!Storage.Consensus_keys}, + {!Storage.Contract.Consensus_key}, and + {!Storage.Contract.Pending_consensus_keys}. *) + type error += | Invalid_consensus_key_update_noop of Cycle_repr.t | Invalid_consensus_key_update_active -- GitLab From 93b00b14535dfecece420867a88229bae489e762 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 12 Oct 2022 09:56:44 +0200 Subject: [PATCH 2/7] doc: better describe typo trains in contributing.rst --- docs/developer/contributing.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index 4b9cc52d46d7..a9031db248de 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -25,10 +25,10 @@ Stretch*), the network you are connected to (e.g. *Carthagenet*), the binary or component (e.g. *tezos-node crashes* or *rpc X returns Y while Z was expected*). -Going further -~~~~~~~~~~~~~ +Fixing typos +~~~~~~~~~~~~ -You may also want to fix some typos and minor errors or incoherencies in the *documentation*, which is situated in the ``docs/`` subfolder of the code repository. +You may also want to fix some typos and minor errors or incoherencies in the *documentation*, which is situated in the ``docs/`` subfolder of the code repository, or within *comments* or *docstrings* within the code. Small tweaks like these can be contributed without creating a merge request and commits can rather be pushed directly to the ``typo-doc`` branch in the ``tezos/tezos`` repository. This branch is regularly merged into the master branch, e.g., every one or two weeks. (If the branch has been automatically deleted following a merge, just create it again.) 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. @@ -38,7 +38,10 @@ The current edition of the typo train MR can be found in meta-issue :gl:`#2329`. If you don't have enough permissions to push to the branch above, you can still make commits in your own fork of the Octez repository, and ask for them to be cherry-picked on the typo/train on the ``#documentation`` channel on the Tezos Dev Slack space. Alternatively, you may of course create your own MRs for submitting your changes, without using the typo train. -To directly contribute to the *codebase*, expertise in a few areas is necessary. +Going further +~~~~~~~~~~~~~ + +To directly contribute to the *code* itself, expertise in a few areas is necessary. First, make sure that you are proficient enough in OCaml. The community website https://ocaml.org gives a few useful pointers for that. In -- GitLab From 8d6a379b85e9b68c03453d1bcbcb713bb0bcd86d Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 12 Oct 2022 09:57:26 +0200 Subject: [PATCH 3/7] doc: explain notion of subtraction underflow in RPC errors --- src/proto_alpha/lib_protocol/tez_repr.ml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/proto_alpha/lib_protocol/tez_repr.ml b/src/proto_alpha/lib_protocol/tez_repr.ml index c8a8aa98b699..2c16dfa99dbe 100644 --- a/src/proto_alpha/lib_protocol/tez_repr.ml +++ b/src/proto_alpha/lib_protocol/tez_repr.ml @@ -205,7 +205,9 @@ let () = pp opb id) - ~description:("A subtraction of two " ^ id ^ " amounts underflowed") + ~description: + ("A subtraction of two " ^ id + ^ " amounts underflowed (i.e., would have led to a negative amount)") (obj1 (req "amounts" (tup2 encoding encoding))) (function Subtraction_underflow (a, b) -> Some (a, b) | _ -> None) (fun (a, b) -> Subtraction_underflow (a, b)) ; -- GitLab From d3aed9b3ef5da8fd173a9b72c1fe17b86c4b3bac Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Tue, 11 Oct 2022 17:39:12 +0200 Subject: [PATCH 4/7] doc/testing: remove outdated info on `gitlab-runner` --- docs/developer/testing.rst | 58 ++++---------------------------------- 1 file changed, 5 insertions(+), 53 deletions(-) diff --git a/docs/developer/testing.rst b/docs/developer/testing.rst index 991e51012cb4..3089af6c57cb 100644 --- a/docs/developer/testing.rst +++ b/docs/developer/testing.rst @@ -112,18 +112,12 @@ Typical use cases: Example tests: - Unit tests for :src:`src/lib_requester`, in :src:`src/lib_requester/test/test_requester.ml`. To execute them locally, run ``dune build @src/lib_requester/runtest`` in - the Tezos root. To execute them on :ref:`your own machine - ` using the GitLab CI system, run - ``gitlab-runner exec docker unit:requester``. + the Tezos root. - Integration tests for the P2P layer in the shell. For instance :src:`src/lib_p2p/test/test_p2p_pool.ml`. This test forks a set of processes that exercise large parts of the P2P layer. To execute it locally, run ``dune build @runtest_p2p_pool`` in the Tezos - root. To execute the P2P tests on :ref:`your own machine - ` using the GitLab CI system, run - ``gitlab-runner exec docker unit:p2p``. The job-name - ``unit:p2p`` is ill-chosen, since the test is in fact an - integration test. + root. References: - `Alcotest README `_. @@ -203,15 +197,11 @@ Example tests: interpreter (in :src:`tests_python/tests_alpha/test_contract_opcodes.py`). To execute it locally, run ``cd tests_python && poetry run pytest tests/test_contract_opcodes.py`` - in the Tezos root. To execute them on :ref:`your own machine - ` using the GitLab CI system, run - ``gitlab-runner exec docker integration:contract_opcodes``. + in the Tezos root. - Setting up networks of nodes and ensuring their connection (in :src:`tests_python/tests_alpha/test_p2p.py`). To execute it locally, run ``cd tests_python && poetry run pytest tests/test_p2p.py`` in - the Tezos root. To execute them on :ref:`your own machine - ` using the GitLab CI system, run - ``gitlab-runner exec docker integration:p2p``. + the Tezos root. References: - `Pytest Documentation `_ @@ -571,8 +561,7 @@ Other For other types of tests, you need to manually modify the :src:`.gitlab-ci.yml`. Please refer to the `GitLab CI Pipeline Reference `_. A helpful tool for - this task is the `CI Lint tool `_, and ``gitlab-runner``, - introduced in the :ref:`next section `. + this task is the `CI Lint tool `_. Test coverage in merge requests ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -633,43 +622,6 @@ contains the HTML coverage report. GitLab also produces a `graph of the coverage ratio over time `_. - - - -.. _executing_gitlab_ci_locally: - -Executing the GitLab CI locally -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -GitLab offers the ability to run jobs defined in the :src:`.gitlab-ci.yml` file on your own machine. -This is helpful to debug the CI pipeline. -For this, you need to setup ``gitlab-runner`` on your machine. -To avoid using outdated versions of the binary, it is recommended to install a -`release from the development repository `_. - -``gitlab-runner`` works with the concept of `executor`. We recommend to use the -``docker`` executor to sandbox the environment the job will be executed in. This -supposes that you have docker installed on your machine. - -For example, if you want to run the job ``check_python_linting`` which checks the Python syntax, you can use: - -.. code-block:: bash - - gitlab-runner exec docker check_python_linting - -Note that the first time you execute a job, it may take a long time because it -requires downloading the docker image, and ``gitlab-runner`` is not verbose on this -subject. For instance, if Tezos' opam repository has changed, requiring -a refresh of the locally cached docker image. - -Local changes must be committed (but not necessarily pushed remotely) -before executing the job locally. Indeed, ``gitlab-runner`` will clone -the head of the current local branch to execute the job. - -Another limitation is that only single jobs can be executed using -``gitlab-runner``. For instance, there is no direct way of executing all -jobs in the stage ``test``. - Conventions ----------- -- GitLab From acfe886b30572ee0a7128f435c4728fdc2348b63 Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Fri, 14 Oct 2022 17:18:16 +0200 Subject: [PATCH 5/7] Docs: Fix testnet links in [transaction_rollups.rst] --- docs/alpha/transaction_rollups.rst | 2 +- docs/kathmandu/transaction_rollups.rst | 2 +- docs/lima/transaction_rollups.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/alpha/transaction_rollups.rst b/docs/alpha/transaction_rollups.rst index b3270031a1aa..76762e7a2ddb 100644 --- a/docs/alpha/transaction_rollups.rst +++ b/docs/alpha/transaction_rollups.rst @@ -588,7 +588,7 @@ provides a shell with the rollup node and client available in the Similarly to other Octez binaries like the baker, there exists a rollup node and client for each version of the Tezos protocol. You can use the ``alpha`` binaries on testnets like `Mondaynet or - Dailynet _`. This is the recommended way to + Dailynet `_. This is the recommended way to experiment with Transaction Rollups, as the finality period on Mondaynet and Dailynet is significantly shorter than on mainnet or other testnets. diff --git a/docs/kathmandu/transaction_rollups.rst b/docs/kathmandu/transaction_rollups.rst index d2198cae3087..55ba0f68e348 100644 --- a/docs/kathmandu/transaction_rollups.rst +++ b/docs/kathmandu/transaction_rollups.rst @@ -582,7 +582,7 @@ provides a shell with the rollup node and client available in the Similarly to other Octez binaries like the baker, there exists a rollup node and client for each version of the Tezos protocol. You can use the ``014-PtKathma`` binaries on testnets like - `Kathmandunet _` (``--network + `Kathmandunet `_ (``--network kathmandunet``). Note that, compared to testnets like Mondaynet or Dailynet, Kathmandunet is using the same protocol constants as Mainnet, meaning the finality period is 40,000 blocks (about 2 diff --git a/docs/lima/transaction_rollups.rst b/docs/lima/transaction_rollups.rst index e40488ec8c57..8a1b4f2142c2 100644 --- a/docs/lima/transaction_rollups.rst +++ b/docs/lima/transaction_rollups.rst @@ -588,7 +588,7 @@ provides a shell with the rollup node and client available in the Similarly to other Octez binaries like the baker, there exists a rollup node and client for each version of the Tezos protocol. You can use the ``alpha`` binaries on testnets like `Mondaynet or - Dailynet _`. This is the recommended way to + Dailynet `_. This is the recommended way to experiment with Transaction Rollups, as the finality period on Mondaynet and Dailynet is significantly shorter than on mainnet or other testnets. -- GitLab From f9997e10796bf400baf958a175deed3a20ee058a Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Mon, 17 Oct 2022 09:42:26 +0200 Subject: [PATCH 6/7] docs/snapshots: fix ipfs.io link --- docs/user/snapshots.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/snapshots.rst b/docs/user/snapshots.rst index 95705758e934..6dac8d6b4c92 100644 --- a/docs/user/snapshots.rst +++ b/docs/user/snapshots.rst @@ -168,7 +168,7 @@ represented as *cemented cycles* and will stay as it is for ever. Only the rest of the file contains data relative to the snapshot's target block, such as the current incomplete cycle and the block's associated ledger state. This canonical representation is well suited for -distributing snapshots through `IPFS `_. +distributing snapshots through `IPFS `_. Export capabilities -- GitLab From 553829cc613d74acf27a6c78ab40e9c2b905ba54 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 20 Oct 2022 10:36:36 +0200 Subject: [PATCH 7/7] doc: use octez-snoop instead of tezos-snoop --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index 8515d526e96b..65f5e091213d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -56,7 +56,7 @@ manuals: \ @../tezos-admin-client man -verbosity 3 -format html | sed "s#${HOME}#\$$HOME#g" > api/tezos-admin-client.html @../tezos-signer man -verbosity 3 -format html | sed "s#${HOME}#\$$HOME#g" > api/tezos-signer.html @../tezos-codec man -verbosity 3 -format html | sed "s#${HOME}#\$$HOME#g" > api/tezos-codec.html - @../tezos-snoop man -verbosity 3 -format html | sed "s#${HOME}#\$$HOME#g" > api/tezos-snoop.html + @../octez-snoop man -verbosity 3 -format html | sed "s#${HOME}#\$$HOME#g" > api/tezos-snoop.html # artificially depend on docexes to avoid concurrent dunes .PHONY: odoc -- GitLab