From f2f4e624c49cb361dc3fbaeead8be99536c596cb Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 26 Apr 2022 10:41:58 +0200 Subject: [PATCH 01/13] doc: mention that tezos-node does not display the options & args of each command --- docs/shell/cli-commands.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/shell/cli-commands.rst b/docs/shell/cli-commands.rst index 7d32fc880077..2e63c317b52d 100644 --- a/docs/shell/cli-commands.rst +++ b/docs/shell/cli-commands.rst @@ -59,3 +59,6 @@ The command line of the Tezos node is not currently documented as a web page, bu you can obtain it in Unix manual format by running the node with no arguments:: tezos-node + +The above command briefly shows the available node commands. +Each command accepts its own set of options and arguments, see :doc:`../user/node-configuration`. -- GitLab From 7195d04503a764d3e82d849336197944106a7305 Mon Sep 17 00:00:00 2001 From: Bruno Deferrari Date: Mon, 18 Apr 2022 14:34:53 -0300 Subject: [PATCH 02/13] Docs: replace `--disable-precheck` with correct `--disable-mempool-precheck` --- docs/shell/prevalidation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/shell/prevalidation.rst b/docs/shell/prevalidation.rst index 210c31ab625e..a98382e6000a 100644 --- a/docs/shell/prevalidation.rst +++ b/docs/shell/prevalidation.rst @@ -65,7 +65,7 @@ applied, then the operation is propagated over the gossip network. Currently, the ``precheck`` filter is only implemented for manager operations. The prevalidator makes the assumption that it is faster to run than ``apply_operation``. -It can be disabled via the ``--disable-precheck`` node option. +It can be disabled via the ``--disable-mempool-precheck`` node option. The ``postfilter`` is executed on applied operations and can be used to reject some of them based on their respective (application) receipts. -- GitLab From 81bd8f448d7ac1bab0c12ef6b8d34f2a9fa12113 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 26 Apr 2022 11:44:24 +0200 Subject: [PATCH 03/13] doc: more instructions on the typo train with/out push acess to NL/typo-doc branch --- docs/developer/contributing.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index b99948d0a10b..d3a6e53b6fd0 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -29,11 +29,15 @@ Going further ~~~~~~~~~~~~~ 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. -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. +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. 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`. +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. First, make sure that you are proficient enough in OCaml. The community -- GitLab From 098e1aea484cfa5f0730d8a47a3fdfb7ff96108b Mon Sep 17 00:00:00 2001 From: Eugen Zalinescu Date: Fri, 29 Apr 2022 12:09:40 +0200 Subject: [PATCH 04/13] docs: fix typo in 'set deposit limit' command --- docs/alpha/consensus.rst | 4 ++-- docs/ithaca/consensus.rst | 4 ++-- docs/jakarta/consensus.rst | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index 675448c6cfe4..6d2854b1449b 100644 --- a/docs/alpha/consensus.rst +++ b/docs/alpha/consensus.rst @@ -179,9 +179,9 @@ not the other way around.): - ``spendable balance`` is obtained with ``../context/contracts//balance`` Delegates can set an upper limit to their frozen deposits with the -commands ``tezos-client set deposit limit for to +command ``tezos-client set deposits limit for to ``, and unset this limit with the command ``tezos-client -unset deposit limit for ``. These commands are implemented by +unset deposits limit for ``. These commands are implemented using a new manager operation ``Set_deposits_limit``. When emitting such a command in cycle ``c``, it affects the active stake for cycles starting with ``c + PRESERVED_CYCLES + 1``; the new active stake is diff --git a/docs/ithaca/consensus.rst b/docs/ithaca/consensus.rst index e0b0ee53fcf9..574bc84624fa 100644 --- a/docs/ithaca/consensus.rst +++ b/docs/ithaca/consensus.rst @@ -185,9 +185,9 @@ not the other way around.): - ``spendable balance`` is obtained with ``../context/contracts//balance`` Delegates can set an upper limit to their frozen deposits with the -commands ``tezos-client set deposit limit for to +command ``tezos-client set deposits limit for to ``, and unset this limit with the command ``tezos-client -unset deposit limit for ``. These commands are implemented by +unset deposits limit for ``. These commands are implemented using a new manager operation ``Set_deposits_limit``. When emitting such a command in cycle ``c``, it affects the active stake for cycles starting with ``c + PRESERVED_CYCLES + 1``; the new active stake is diff --git a/docs/jakarta/consensus.rst b/docs/jakarta/consensus.rst index 1148a6540157..336c3ca3c35c 100644 --- a/docs/jakarta/consensus.rst +++ b/docs/jakarta/consensus.rst @@ -179,9 +179,9 @@ not the other way around.): - ``spendable balance`` is obtained with ``../context/contracts//balance`` Delegates can set an upper limit to their frozen deposits with the -commands ``tezos-client set deposit limit for to +command ``tezos-client set deposits limit for to ``, and unset this limit with the command ``tezos-client -unset deposit limit for ``. These commands are implemented by +unset deposits limit for ``. These commands are implemented using a new manager operation ``Set_deposits_limit``. When emitting such a command in cycle ``c``, it affects the active stake for cycles starting with ``c + PRESERVED_CYCLES + 1``; the new active stake is -- GitLab From ac87a1582be67c7b80e38a366628298da12f2a0b Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 29 Apr 2022 15:30:20 +0200 Subject: [PATCH 05/13] doc: remove print of CI variables for debug --- .gitlab/ci/doc.yml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/.gitlab/ci/doc.yml b/.gitlab/ci/doc.yml index 52d3f32ace6f..a9c6b6bdb3b1 100644 --- a/.gitlab/ci/doc.yml +++ b/.gitlab/ci/doc.yml @@ -62,10 +62,6 @@ publish:documentation: # Give access to the Python dependencies/executables - . $HOME/.venv/bin/activate script: - - echo "$CI_SERVER_URL/$CI_PROJECT_NAMESPACE/$CI_PROJECT_NAME/" - - echo "$CI_COMMIT_REF_NAME" - - echo "$CI_PROJECT_URL" - - echo "$CI_MERGE_REQUEST_SOURCE_PROJECT_URL" - if [ "${CI_COMMIT_REF_NAME}" == "master" ] ; then make -C docs full ; git clone --depth 5 git@gitlab.com:${CI_PROJECT_NAMESPACE}/${CI_PROJECT_NAMESPACE}.gitlab.io gitlab.io ; -- GitLab From caa2de7d3b1dd2cf3b0c5b146a72033ec9ea9608 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 29 Apr 2022 17:12:47 +0200 Subject: [PATCH 06/13] doc: fix error on label ref to zcash setup --- docs/introduction/howtouse.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst index f7a04d62e307..c9d41576c7f5 100644 --- a/docs/introduction/howtouse.rst +++ b/docs/introduction/howtouse.rst @@ -126,7 +126,7 @@ connect to the network:: .. note:: If the node prompts you to install the Zcash parameter file, follow - the :ref`corresponding instructions `. + the :ref:`corresponding instructions `. The identity comprises a pair of cryptographic keys that nodes use to encrypt messages sent to each other, and an -- GitLab From 165d9958b3560545f2604328253c50334dad4e4e Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Mon, 2 May 2022 14:50:50 +0200 Subject: [PATCH 07/13] doc: fix doc of RPC get .../context/contracts (solve issue #1786) --- src/proto_alpha/lib_protocol/contract_services.ml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/proto_alpha/lib_protocol/contract_services.ml b/src/proto_alpha/lib_protocol/contract_services.ml index 07f0b1c454bd..75a3a50a1631 100644 --- a/src/proto_alpha/lib_protocol/contract_services.ml +++ b/src/proto_alpha/lib_protocol/contract_services.ml @@ -233,7 +233,7 @@ module S = struct let list = RPC_service.get_service ~description: - "All existing contracts (including non-empty default contracts)." + "All existing contracts (excluding empty implicit contracts)." ~query:RPC_query.empty ~output:(list Contract.encoding) custom_root -- GitLab From 4f83c0d31767c3eed6414ea78b3a24650bc3673d Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Mon, 2 May 2022 13:58:54 +0200 Subject: [PATCH 08/13] Docs/MR process: Remove mention of unused WIP prefix --- docs/developer/contributing.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index d3a6e53b6fd0..34e9c4a1b5a6 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -123,14 +123,11 @@ While the code is still not ready to be peer reviewed, but it is merely a work in progress, the developer prefixes the MR with ``Draft:`` and assigns it to themselves. This will tell everybody they can look at the code, comment, but there is still work to be done -and the branch can change and history be rewritten. Alternatively, the -MR title can be prefixed with ``WIP:``. ``Draft:`` prefix is -sometimes set automatically by GitLab, so ``WIP:`` is in a sense less -ambiguous. +and the branch can change and history be rewritten. Finally, when the code is ready for the :ref:`code review -`, the developer removes the Draft status (or ``WIP:`` -prefix) of the MR and freezes the branch. From this moment on, the +`, the developer removes the Draft status +of the MR and freezes the branch. From this moment on, the developer will refrain from rewriting history, but he/she can add new commits and rebase the branch for syncing it with master (this can be done regularly to make sure the branch does not get stale). At this -- GitLab From 67cd86fa800fefb350342a4c7c1ea5e42e29cc33 Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Mon, 2 May 2022 14:00:11 +0200 Subject: [PATCH 09/13] Docs/MR process: add some woke --- docs/developer/contributing.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index 34e9c4a1b5a6..dcf2448880ff 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -128,17 +128,17 @@ and the branch can change and history be rewritten. Finally, when the code is ready for the :ref:`code review `, the developer removes the Draft status of the MR and freezes the branch. From this moment on, the -developer will refrain from rewriting history, but he/she can add new +developer will refrain from rewriting history, but they can add new commits and rebase the branch for syncing it with master (this can be done regularly to make sure the branch does not get stale). At this point the developer interacts with the reviewers to address their comments and suggestions. GitLab allows both to comment on the code and to add general comments -on the MR. Each comment should be addressed by the developer. He/she +on the MR. Each comment should be addressed by the developer. They can add additional commits to address each comment. This incremental approach will make it easier for the reviewer to keep interacting till -each discussion is resolved. When the reviewer is satisfied, he/she +each discussion is resolved. When the reviewer is satisfied, they will mark the discussion resolved. When all discussions are resolved, and the MR has got at least two @@ -398,7 +398,7 @@ action is required to get the merge request moving. Example actions include: - merge; - find someone else who can get the merge request moving. -The assignee will thus often be one of the reviewers (if he needs to review +The assignee will thus often be one of the reviewers (if they needs to review or respond to a comment) or one of the merge request authors (if they need to update the code or respond to a comment). -- GitLab From 5c231b9059391817a9f14c1cace6ca14c032da72 Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Mon, 2 May 2022 14:04:04 +0200 Subject: [PATCH 10/13] Docs/MR process: some spelling --- docs/developer/contributing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index dcf2448880ff..cc7ec8329138 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -145,7 +145,7 @@ When all discussions are resolved, and the MR has got at least two approvals from Octez Merge Team members, the developer should squash any fix-up commits that were applied (remembering to edit the commit message appropriately). Then anyone can assign the MR to the `Nomadic -Margebot `__, which will +Marge-bot `__, which will automatically rebase the branch on top of master and finally merge it. .. _preparing_MR: @@ -480,7 +480,7 @@ this additional dedicated guide: contributing-adding-a-new-opam-dependency -In the special case where your MR adds a new Python, Rust, Javascript, or other +In the special case where your MR adds a new Python, Rust, JavaScript, or other dependency, additional steps must also be followed. * for Python, you can refer to the related section in the :ref:`python testing documentation `. @@ -648,7 +648,7 @@ pitfalls a code reviewer should avoid. have a different reaction to it and impact on the quality of this work. This general remark is valid for any comment. -When reviewing MRs involving documentation, you may check the built documentation directly within the Gitlab interface, see :ref:`build_doc_ci`. +When reviewing MRs involving documentation, you may check the built documentation directly within the GitLab interface, see :ref:`build_doc_ci`. .. _merge_bot: -- GitLab From c8f3a243927bf1def65582603a228833480f15cc Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Mon, 2 May 2022 14:58:12 +0200 Subject: [PATCH 11/13] Docs/MR process: smaller fixes --- docs/developer/contributing.rst | 16 ++++++++-------- docs/developer/merge_team.rst | 6 +++--- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index cc7ec8329138..f61d1e1e1b21 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -166,7 +166,7 @@ While working on your branch to prepare a Merge Request, make sure you respect t the branch name. + Use ``opam`` in the branch name if you want to explicitly trigger - the OPAM packaging pipeline. Note that any OPAM related changes + the opam packaging pipeline. Note that any opam related changes will automatically trigger it. + Use ``doc`` in the branch name if you change the documentation. + Use ``arm64`` in the branch name if you need to build ARM64 artifacts. @@ -195,8 +195,8 @@ While working on your branch to prepare a Merge Request, make sure you respect t non-obvious design choice), you should document them in this file header, but in a separate "History" section. - If you add new functions to an interface, don’t forget to - document the function in the interface (in the corresponding .mli file; or, - if there is no .mli file, directly in the .ml file) + document the function in the interface (in the corresponding ``.mli`` file; or, + if there is no ``.mli`` file, directly in the ``.ml`` file) - If you add a new RPC endpoint or modify an existing one, be sure to take into account the impact on :ref:`RPC security `. - If you modify the user API (e.g. add or change a configuration parameter or @@ -290,7 +290,7 @@ Therefore, when creating your MR, observe the following rules: + ``ci--opam`` is for triggering the opam packaging tests pipeline. + ``ci--docs`` is for testing some scripts in the documentation (e.g. Octez installation scenarios). - + ``ci--docker`` is for publishing the docker image of the MR. + + ``ci--docker`` is for publishing the Docker image of the MR. + ``ci--arm64`` is for building on the ARM64 architecture. - *MR Options*: When opening an MR you should probably tick the following @@ -426,7 +426,7 @@ To find reviewers, either: - Look at authors of the code you are modifying using `git blame `_. - Ask help to the :ref:`merge coordinator `, either - by asking him/her on Slack or mentioning them in a comment (see next paragraph). + by asking them on Slack or mentioning them in a comment (see next paragraph). Depending on your `GitLab role `_ you may or may not be able to use the *Reviewers* field for specifying @@ -487,7 +487,7 @@ dependency, additional steps must also be followed. * the Rust dependencies are located in the GitLab repository `tezos-rust-libs `_ and the instructions are listed there. For others, there is currently no dedicated guide. Do not hesitate to ask for -help on the ``#devteam`` channel on the `tezos-dev` Slack. +help on the ``#devteam`` channel on the `tezos-dev `_ Slack. .. _protocol_mr: @@ -535,7 +535,7 @@ Merge Request Approvals ~~~~~~~~~~~~~~~~~~~~~~~ Two approvals from different Octez :doc:`Octez merge team ` members are required for merge -requests to be merged. Both approvals must result from independent thorough +requests to be merged. Both approvals must result from independent, thorough reviews. After both reviews, the second approver will also typically merge. However, for less critical parts of the code, an Octez merge team member may @@ -568,7 +568,7 @@ painful for everybody. The reviewer is your ally, not your enemy. Did I leave a :ref:`TODO/FIXME comment ` without an issue number? - Docstrings: Did I export a new function? Each exported - function should be documented in the corresponding ``mli`` (or directly in the ``ml`` file if there is no ``mli``). + function should be documented in the corresponding ``.mli`` (or directly in the ``.ml`` file if there is no ``.mli``). - README: Did I check whether my changes impact the corresponding README file(s)? diff --git a/docs/developer/merge_team.rst b/docs/developer/merge_team.rst index b4d0f556ef3a..b0fa49d86815 100644 --- a/docs/developer/merge_team.rst +++ b/docs/developer/merge_team.rst @@ -22,7 +22,7 @@ the next protocol (``src/proto_alpha/lib_protocol/``). Companies that contribute `tezos/tezos `_ reach a consensus to decide what gets in the Alpha protocol, i.e. in the proposal of the next upgrade. In particular, other companies -can fork this repo and do their own protocol proposals. +can fork this repository and do their own protocol proposals. .. _merge_coordinator: @@ -79,8 +79,8 @@ The Octez merge team is always looking for software engineers with at least the - You are relatively skilled in one of the technologies used in the ``tezos/tezos`` repository, i.e. ``OCaml``, ``python``, ``CI``, building, packaging, etc. -To apply for being included in the Octez merge team, contact an existing member -on the `tezos-dev `_ Slack. Your application +To apply for being included in the Octez merge team, contact the :ref:`merge coordinator ` or +an existing member on the `tezos-dev `_ Slack. Your application will be discussed during the next weekly meeting of the Octez merge team. Helping the Octez Merge Team -- GitLab From e36490e388f18d8318ad72be40cfc62b04c3e2fd Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 3 May 2022 09:42:45 +0200 Subject: [PATCH 12/13] doc: advise to delete Sprout parameters installed by fetch-params.sh (solve issue #1960) --- docs/introduction/howtoget.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/introduction/howtoget.rst b/docs/introduction/howtoget.rst index 97afc6c0ced9..978771c91d3a 100644 --- a/docs/introduction/howtoget.rst +++ b/docs/introduction/howtoget.rst @@ -476,6 +476,8 @@ and ``sapling-output.params``. Here is where you should expect to find those fil Some operating systems may not be covered by the list of directories above. If Zcash is located elsewhere on your system (typically, on MacOS X), you may try creating a symbolic link such as: ``ln -s ~/Library/Application\ Support/ZcashParams ~/.zcash-params``. +Note that the script ``fetch-params.sh`` downloads a third file containing parameters for Sprout (currently called ``sprout-groth16.params``), which is not loaded by Sapling and can be deleted to save a significant amount of space (this file is *much* bigger than the two other files). + Get the sources ~~~~~~~~~~~~~~~ -- GitLab From 23f5d64b424fbbda038fd3af1063368b0ef4b1ed Mon Sep 17 00:00:00 2001 From: Victor Allombert Date: Fri, 6 May 2022 08:32:41 +0200 Subject: [PATCH 13/13] Doc: be more precise regarding rolling mode's bootstrap --- docs/user/history_modes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/history_modes.rst b/docs/user/history_modes.rst index 656777d754d2..40fa4f56818a 100644 --- a/docs/user/history_modes.rst +++ b/docs/user/history_modes.rst @@ -41,7 +41,7 @@ Three history modes are provided: + Only requires a minimal and bounded disk storage. + Can run on low resources architectures. - + Can be bootstrapped within minutes. + + Can be bootstrapped within minutes, thanks to a rolling snapshot import. * Downsides -- GitLab