From cf8b9aabe425833c9ce004fb1cac720c0135b374 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 25 Jun 2024 15:46:19 +0200 Subject: [PATCH 01/10] doc: fix misalignment in Paris glossary --- docs/paris/glossary.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/paris/glossary.rst b/docs/paris/glossary.rst index c1d8fa3f373f..9338ec2c7209 100644 --- a/docs/paris/glossary.rst +++ b/docs/paris/glossary.rst @@ -379,9 +379,9 @@ _`Staker` The security deposit accrues to the stake of the implicit account's delegate and is subject to slashing in case the delegate misbehaves -- see :ref:`Slashing`. - _`Transaction` - An operation_ to transfer tez between two accounts, or to run the code of a - `smart contract`_. +_`Transaction` + An operation_ to transfer tez between two accounts, or to run the code of a + `smart contract`_. _`Validation pass` An index (a natural number) associated with a particular kind of -- GitLab From 12737430f38545fd2d0e77972cd0248b051ce43a Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 27 Jun 2024 15:09:49 +0200 Subject: [PATCH 02/10] doc: link breaking_changes to RPC versioning --- docs/introduction/breaking_changes.rst | 8 +++++--- docs/introduction/versioning.rst | 1 + 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/introduction/breaking_changes.rst b/docs/introduction/breaking_changes.rst index 0f41bdf0e3aa..2a185da63b88 100644 --- a/docs/introduction/breaking_changes.rst +++ b/docs/introduction/breaking_changes.rst @@ -6,12 +6,14 @@ different Protocols or Octez versions. It complements the "Breaking changes" sections in the development changelogs by providing more context and/or less fragmented mentions. -For each change, there may be a subsection ``deprecation`` and ``breaking -changes``. The first subsection will explain what changes can be made during a -deprecation phase to adapt smoothly to the new changes. The second subsection +For each change, there may be subsections ``deprecation`` and ``breaking +changes``. The former subsection will explain what changes can be made during a +deprecation phase to adapt smoothly to the new changes. The latter subsection will present the changes that can not be done by the deprecation mechanism and that may be breaking. +In the particular case of RPC changes, you may consult complementary information on :ref:`RPC versioning `, covering how new versions are introduced, the deprecation policy, and a concrete calendar of RPCs planned to be removed. + Attestations ------------ diff --git a/docs/introduction/versioning.rst b/docs/introduction/versioning.rst index c6e124538000..80473fb9edb4 100644 --- a/docs/introduction/versioning.rst +++ b/docs/introduction/versioning.rst @@ -21,6 +21,7 @@ When new features are needed by a proposed protocol, or if the protocol API is c see :ref:`Protocol environment versions `. The new environment is delivered as part of a new Octez release. +.. _rpc_versioning: RPC Versioning -------------- -- GitLab From e241cbce22b285947112ac27b9795a6165f9c409 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 4 Jul 2024 09:24:41 +0200 Subject: [PATCH 03/10] doc: fix KiB equivalence in dal_support --- docs/alpha/dal_support.rst | 2 +- docs/paris/dal_support.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/alpha/dal_support.rst b/docs/alpha/dal_support.rst index b7597caad8ec..644363e4370c 100644 --- a/docs/alpha/dal_support.rst +++ b/docs/alpha/dal_support.rst @@ -81,6 +81,6 @@ This section describes the protocol constants specific to the DAL as well as the - ``attestation_threshold`` (66): The percentage of shards attested for a given slot to declare the slot available - ``blocks_per_epoch`` (1): Unused. Could be removed in the future - ``page_size`` (3967B, ~4KiB): The size of a page (see :ref:`dal_slots`) -- ``slot_size`` (126944B, ~1MiB): The size of a slot (see :ref:`dal_slots`) +- ``slot_size`` (126944B, ~128KiB): The size of a slot (see :ref:`dal_slots`) - ``redundancy_factor`` (8): The erasure-code factor (see :ref:`dal_slots`) - ``number_of_shards`` (512): The number of shards per slot (see :ref:`dal_slots`) diff --git a/docs/paris/dal_support.rst b/docs/paris/dal_support.rst index 8766fe48a496..45da05d025d4 100644 --- a/docs/paris/dal_support.rst +++ b/docs/paris/dal_support.rst @@ -82,6 +82,6 @@ This section describes the protocol constants specific to the DAL as well as the - ``attestation_threshold`` (66): The percentage of shards attested for a given slot to declare the slot available - ``blocks_per_epoch`` (1): Unused. Could be removed in the future - ``page_size`` (3967B, ~4KiB): The size of a page (see :ref:`dal_slots`) -- ``slot_size`` (126944B, ~1MiB): The size of a slot (see :ref:`dal_slots`) +- ``slot_size`` (126944B, ~128KiB): The size of a slot (see :ref:`dal_slots`) - ``redundancy_factor`` (8): The erasure-code factor (see :ref:`dal_slots`) - ``number_of_shards`` (512): The number of shards per slot (see :ref:`dal_slots`) -- GitLab From 449e09d0c5ee0d58062ce4956b8684d156a1f6db Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 5 Jul 2024 15:49:10 +0200 Subject: [PATCH 04/10] doc: fix structure in node-configuration page --- docs/user/node-configuration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user/node-configuration.rst b/docs/user/node-configuration.rst index 1cd60951a98f..c48bcac1b8c4 100644 --- a/docs/user/node-configuration.rst +++ b/docs/user/node-configuration.rst @@ -189,7 +189,7 @@ modifying the file. Otherwise they'll be shadowed by the more general rule. Examples -~~~~~~~~ +"""""""" :: @@ -247,7 +247,7 @@ in order to accommodate each specific setup. .. _default_acl: Default ACL for RPC -------------------- +""""""""""""""""""" The default ACL for RPC depends on the listening address that the node is using. -- GitLab From e16ea5559c7d79143b21fab09562a6694db6ad96 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 10 Jul 2024 10:43:52 +0200 Subject: [PATCH 05/10] doc: fix TZT label in protocols --- docs/alpha/michelson.rst | 2 +- docs/paris/michelson.rst | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/alpha/michelson.rst b/docs/alpha/michelson.rst index 90d5c320901e..cb7d6111f98b 100644 --- a/docs/alpha/michelson.rst +++ b/docs/alpha/michelson.rst @@ -2020,7 +2020,7 @@ The language is implemented in OCaml as follows: ``Prim ("If", ...)`` into an ``If``, a ``Prim ("Dup", ...)`` into a ``Dup``, etc. -.. michelson_tzt_alpha: +.. _michelson_tzt_alpha: TZT, a Syntax extension for writing unit tests ---------------------------------------------- diff --git a/docs/paris/michelson.rst b/docs/paris/michelson.rst index aa024dbd39ef..8b5f6576befe 100644 --- a/docs/paris/michelson.rst +++ b/docs/paris/michelson.rst @@ -1982,7 +1982,8 @@ The language is implemented in OCaml as follows: ``Prim ("If", ...)`` into an ``If``, a ``Prim ("Dup", ...)`` into a ``Dup``, etc. -.. michelson_tzt_paris: +.. _michelson_tzt: +.. _michelson_tzt_paris: TZT, a Syntax extension for writing unit tests ---------------------------------------------- -- GitLab From 14912e49508f47af707597dd715282f2c6a4062f Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 10 Jul 2024 10:44:26 +0200 Subject: [PATCH 06/10] doc: add TZT to the testing overview --- docs/developer/testing.rst | 37 +++++++++++++++++-------------------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/docs/developer/testing.rst b/docs/developer/testing.rst index 210614da9dd9..d157e0c0589e 100644 --- a/docs/developer/testing.rst +++ b/docs/developer/testing.rst @@ -75,15 +75,12 @@ appropriate for the corresponding component and testing type. The frameworks are linked to a sub-section of this page where the framework is presented in more detail. -.. - MT: :ref:`Michelson unit tests `. - -.. csv-table:: Testing frameworks and their applications in Octez. EXP: :ref:`ppx_expect_section`, AT: :ref:`alcotezt_section`, QC: :ref:`property_based_test`, TZ: :ref:`tezt_section`, LTF: :ref:`long_tezt_section` +.. csv-table:: Testing frameworks and their applications in Octez. EXP: :ref:`ppx_expect_section`, AT: :ref:`alcotezt_section`, QC: :ref:`property_based_test`, TZ: :ref:`tezt_section`, LTF: :ref:`long_tezt_section`, TZT: :ref:`Michelson unit tests ` :header: "Component","Unit","Property","Integration","System","Regression","Performance" "Node",":ref:`AT `",":ref:`QC `",":ref:`AT `",":ref:`TZ `","",":ref:`LTF `" "-- Protocol",":ref:`AT `, :ref:`EXP `",":ref:`QC `","" - "-- -- Michelson interpreter",":ref:`AT `","","",":ref:`TZ `",":ref:`TZ `" + "-- -- Michelson interpreter",":ref:`AT `, :ref:`TZT `","","",":ref:`TZ `",":ref:`TZ `" "Client",":ref:`EXP `",":ref:`QC `","",":ref:`TZ `","",":ref:`LTF `" "Networked nodes","--","",":ref:`TZ `","", "" "Attester","","","","" @@ -232,25 +229,25 @@ Typical use cases: References: - `Alcotest README `_. -.. - .. _michelson_unit_tests: +.. _michelson_unit_tests: + +Michelson unit tests +-------------------- + +The :ref:`TZT syntax extension ` defines a +format for unit tests for Michelson snippets. The +tests written in it are executable: - Michelson unit tests - -------------------- +- through ``octez-client run unit test`` for the Michelson interpreter written in OCaml; +- through ``cargo run --bin tzt_runner`` for the Michelson interpreter written in Rust. - The `Michelson unit test proposal - `__ defines a - format for unit tests for Michelson snippets. If the proposal is eventually accepted, then these - tests will be executable through ``octez-client``. +Example use cases: - Example use cases: - - Verifying the functional (input--output) behavior of snippets of - Michelson instructions. - - Conformance testing for Michelson interpreters. +- Verifying the functional (input--output) behavior of snippets of + Michelson instructions. +- Conformance testing for Michelson interpreters. - References: - - `Merge request defining the Michelson unit test format `_ - - `A conformance test suite for Michelson interpreter using the Michelson unit test format `_ +A `conformance test suite for Michelson interpreters `__ written using the TZT extension is maintained and is used for non-regression testing. .. _gitlab_test_ci: -- GitLab From 9ba2a984f09dbc224e0aa113eff8537c4cc1b79d Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 12 Jul 2024 12:20:04 +0200 Subject: [PATCH 07/10] doc: add case-sensitivity issues to get_troubleshooting --- docs/introduction/get_troubleshooting.rst | 14 +++++++++++++- docs/user/node-configuration.rst | 2 +- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/introduction/get_troubleshooting.rst b/docs/introduction/get_troubleshooting.rst index 5c3be771383d..6235ca8808c4 100644 --- a/docs/introduction/get_troubleshooting.rst +++ b/docs/introduction/get_troubleshooting.rst @@ -11,7 +11,19 @@ Consult the :ref:`Tezos community ` (e.g. the Tezos Stack Excha Generic issues -------------- -N/A +Case-sensitive file paths +~~~~~~~~~~~~~~~~~~~~~~~~~ + +On case-insensitive file systems, which is the default on Windows and MacOS, beware of some related problems. + +In the Octez repository, there are no conflicting file paths differing only in case. +However, depending on how Git extracts your clone, the case of some file paths in your clone may differ from the expected one. + +For example, file :src:`script-inputs/slim-mode-dune` contains a list of source directories (belonging to old protocols) to ignore when building the documentation locally. +If the case of your extracted files does not match the case in that file, you may encounter unexpected behaviors, such as errors when building the documentation on those parts. +(Note that these documentation errors cannot be fixed in old protocols whose code is frozen.) + +If you run into such errors, simply rename your file paths to match the case in the source repository. .. _mixing_llvm_gnu_binutils: diff --git a/docs/user/node-configuration.rst b/docs/user/node-configuration.rst index c48bcac1b8c4..703b79cd5a3a 100644 --- a/docs/user/node-configuration.rst +++ b/docs/user/node-configuration.rst @@ -185,7 +185,7 @@ modifying the file. Rules are always searched from the beginning of the list to the end and the first matching address is returned. Therefore if one wants to put one rule on a specific port on a given host and another rule for all other ports - on the same host, then more specific rules should always be written *first* + on the same host, then more specific rules should always be written *first*. Otherwise they'll be shadowed by the more general rule. Examples -- GitLab From 3129c464d940fc1f1451b1244f6ba4c1fe5e0323 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 12 Jul 2024 13:52:40 +0000 Subject: [PATCH 08/10] doc: name subsections in Breaking changes --- docs/introduction/breaking_changes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/introduction/breaking_changes.rst b/docs/introduction/breaking_changes.rst index 2a185da63b88..aa01c35401bd 100644 --- a/docs/introduction/breaking_changes.rst +++ b/docs/introduction/breaking_changes.rst @@ -6,7 +6,7 @@ different Protocols or Octez versions. It complements the "Breaking changes" sections in the development changelogs by providing more context and/or less fragmented mentions. -For each change, there may be subsections ``deprecation`` and ``breaking +For each change, there may be subsections ``Deprecation`` and ``Breaking changes``. The former subsection will explain what changes can be made during a deprecation phase to adapt smoothly to the new changes. The latter subsection will present the changes that can not be done by the deprecation mechanism and -- GitLab From be294be2f28ff659a656dfa9904ece1afc65b3a2 Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Wed, 17 Jul 2024 10:57:47 +0200 Subject: [PATCH 09/10] [images/README.md]: note building Docker Octez from public images --- images/README.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/images/README.md b/images/README.md index d23c52f596f1..0cdb80716248 100644 --- a/images/README.md +++ b/images/README.md @@ -134,8 +134,18 @@ see `./scripts/create_docker_image.sh --help`. Like the Octez Docker distribution, the CI images are also built in the tezos/tezos CI. By default, `./scripts/create_docker_image.sh` is -configured to pull the CI images from the CI if they cannot be found -locally. +configured to pull the CI images from the CI's protected Docker +registry if they cannot be found locally. + +Note that if the image you want to use is from a branch that has not +yet been merged to `master`, then it will not be in the protected +Docker registry, but in the public one. To configure the script to use +the public registry: + +``` +$ ./scripts/create_docker_image.sh \ + --ci-image-name $(. ./scripts/version.sh; echo $GCP_PUBLIC_REGISTRY)/tezos/tezos/ci +``` ## Using local CI images -- GitLab From 19a76d5b42603dff6468f4b5ba23dc8bea425a1e Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Mon, 22 Jul 2024 14:21:45 +0200 Subject: [PATCH 10/10] doc: remove snapshot source: Marigold --- docs/user/snapshots.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/user/snapshots.rst b/docs/user/snapshots.rst index 12b0bdb7f2df..05630b2ef12c 100644 --- a/docs/user/snapshots.rst +++ b/docs/user/snapshots.rst @@ -210,4 +210,3 @@ download. These include: * `Tzinit snapshots `_ * `Lambs on acid `_ -* `Marigold snapshots `_ -- GitLab