diff --git a/docs/alpha/dal_support.rst b/docs/alpha/dal_support.rst index b7597caad8ece97445e75e48365fc370fd9eab61..644363e4370c9afee778e9ac943ece005ed3c82c 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/alpha/michelson.rst b/docs/alpha/michelson.rst index 90d5c320901e787c3d292dd97a9bf25756054bd5..cb7d6111f98b1de51854dacc68a3a112d2b707c7 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/developer/testing.rst b/docs/developer/testing.rst index 210614da9dd977f0a20fd5d261053fb2fbd0484e..d157e0c0589e2a9cb5a7fe49595074f375489c53 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: diff --git a/docs/introduction/breaking_changes.rst b/docs/introduction/breaking_changes.rst index 0f41bdf0e3aad7497eabbae105cb3b78f0ca4170..aa01c35401bd35ac0d83d6dfd9b8b33c7ea4f90c 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/get_troubleshooting.rst b/docs/introduction/get_troubleshooting.rst index 5c3be771383d5545ca2ed750512eab9456cfab96..6235ca8808c4262521ed681e98327af4521c84db 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/introduction/versioning.rst b/docs/introduction/versioning.rst index c6e124538000110e8a197916b1018b39893a2456..80473fb9edb4323f16c87f5db0d94398c03f0b03 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 -------------- diff --git a/docs/paris/dal_support.rst b/docs/paris/dal_support.rst index 8766fe48a496789c898ab7c02e274b5120fbf51e..45da05d025d411237827bf08ac94b40fb46aad03 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`) diff --git a/docs/paris/glossary.rst b/docs/paris/glossary.rst index c1d8fa3f373f26f8e02f36d8d0a02cb41ff40434..9338ec2c7209e45977bbdcba316134bf49e0761c 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 diff --git a/docs/paris/michelson.rst b/docs/paris/michelson.rst index aa024dbd39efe047a95c3b6965d3bf28c96ed731..8b5f6576befedf8536464ec5277e1161e74d4297 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 ---------------------------------------------- diff --git a/docs/user/node-configuration.rst b/docs/user/node-configuration.rst index 1cd60951a98f3f12c8ecd7d5bf2244c37d5bc1f5..703b79cd5a3a3abe654b4fc33686cff7d09ec0bd 100644 --- a/docs/user/node-configuration.rst +++ b/docs/user/node-configuration.rst @@ -185,11 +185,11 @@ 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 -~~~~~~~~ +"""""""" :: @@ -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. diff --git a/docs/user/snapshots.rst b/docs/user/snapshots.rst index 12b0bdb7f2dfe4c6d147aac576dfec1770d645d0..05630b2ef12c3f9b6cb1ddf40f861397c858265a 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 `_ diff --git a/images/README.md b/images/README.md index d23c52f596f12f098c917de6faecb834a660f5ad..0cdb80716248d361af09a19c38ec044e95516147 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