From f86dba731f6ebfc61edd10fe0dc745b8b83c0f10 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 6 Apr 2021 09:59:46 +0200 Subject: [PATCH 01/13] doc: talk about the typo train --- docs/developer/contributing.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index 7279f5d356e6..88377a6c7e4b 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -25,11 +25,14 @@ 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 ~~~~~~~~~~~~~ -To directly contribute to the codebase, expertise in a few areas is necessary. +You may also want to fix yourself some typos and minor errors or incoherences in the *documentation*, which is situated in the ``docs/`` subfolder of the code repository. +This kind of small contribution can be done without creating a merge request, by directly pushing commits to the ``typo-train`` branch, which is regularly merged into the master branch, e.g., every one or two weeks. +Of course, all these commits will be reviewed before being integrated. + +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 website https://ocaml.org gives a few useful pointers for that. In -- GitLab From 0e5d4d999633025e1d56450f50d917e6273d22ee Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Tue, 6 Apr 2021 11:45:01 +0200 Subject: [PATCH 02/13] Doc/Snoop: RST fixes --- docs/developer/snoop_example.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/developer/snoop_example.rst b/docs/developer/snoop_example.rst index 2bc819552457..33205761f576 100644 --- a/docs/developer/snoop_example.rst +++ b/docs/developer/snoop_example.rst @@ -231,7 +231,7 @@ Step 3: benchmarking If the results obtained in the previous section are reasonable, we can proceed to the generation of raw timing data. We want -to invoke the ``Blake2b_example`` benchmark and save the resulting data to `./blake2b.workload`. +to invoke the ``Blake2b_example`` benchmark and save the resulting data to ``./blake2b.workload``. We want `500` distinct random inputs, and for each stack we will perform the timing measurement `3000` times. The ``--determinizer`` option specifies how the empirical timing distribution corresponding to the per-stack `3000` samples @@ -313,16 +313,16 @@ At the time of writing, the tool offloads the regression problem to the scikit-l The command performed the following tasks: -- load the workload data from `blake2b.workload`; +- load the workload data from ``blake2b.workload``; - construct a linear regression problem using the chosen model: here, the ``Blake2b_example`` benchmark only provides the ``blake2b`` model; - solve this problem using the specified ``lasso`` algorithm, with the constraint that the inferred coefficients must be positive; -- dump the result of inference to a csv file named `blake2b.csv`; -- save a structured solution (useful for code generation) to `blake2b.sol`; +- dump the result of inference to a csv file named ``blake2b.csv``; +- save a structured solution (useful for code generation) to ``blake2b.sol``; - plot the result of inference. -Let's first have a look at the contents of the CSV solution `blake2b.csv`. +Let's first have a look at the contents of the CSV solution ``blake2b.csv``. .. csv-table:: Inference results :header: "blake2b_const", "blake2b_ns_p_byte" @@ -364,7 +364,7 @@ but the principle is similar. By default, the tool produces integer code by casting floating point constant to integers. The tool produces the following code on ``stdout``: -:: code-block:: ocaml +.. code-block:: ocaml let model_blake2b_codegen size = (int_of_float 144.753899773) + (int_of_float 1.17988921492) * size @@ -389,7 +389,7 @@ Calling the tool: We get: -:: code-block:: ocaml +.. code-block:: ocaml let model_blake2b_codegen size = let v0 = size in -- GitLab From d386f0accdafb69509fd6259f08da5f98d168636 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 6 Apr 2021 10:54:09 +0000 Subject: [PATCH 03/13] fix various typos --- docs/developer/contributing.rst | 14 +++++++------- docs/developer/snoop_example.rst | 4 ++-- docs/releases/version-9.rst | 2 +- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index 88377a6c7e4b..41b1bb3b7e68 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -14,7 +14,7 @@ Reporting issues ~~~~~~~~~~~~~~~~ The simplest way to contribute to Tezos is to report issues that you may -find with the software on `gitlab `__. +find with the software on `GitLab `__. If you are unsure about an issue consult the :ref:`technical support sources ` first and always make sure @@ -55,7 +55,7 @@ While you familiarize yourself with the basics as suggested above, you can have a look at the :ref:`software architecture ` of Tezos. It will give you the main components and their interactions, and links to the -documentations for the various parts. +documentation for the various parts. Now, that you're ready to delve into the code, it is time to know how contributions to the code are submitted, reviewed, and finally accepted into the master branch. @@ -239,7 +239,7 @@ Therefore, when creating your MR, observe the following rules: - Isolate complicated parts of your patch in their own commits. - Put simple, non-controversial commits first. For instance: commits - which fix typos, improve documentation, or are simple enough that + that fix typos, improve documentation, or are simple enough that we may want to merge them even without the rest of the merge request. Even better put them in a separate MR which can be merged easily. @@ -449,7 +449,7 @@ pitfalls a code reviewer should avoid. what else would have to change? How could we make this more maintainable? - Discuss in person for more detailed points: Online comments are useful for - focused technical questions. In many occasions it is more productive to + focused technical questions. On many occasions it is more productive to discuss it in person rather than in the comments. Similarly, if discussion about a point goes back and forth, It will be often more productive to pick it up in person and finish out the discussion. @@ -485,7 +485,7 @@ pitfalls a code reviewer should avoid. - Consider the person you are reviewing: Each developer is a person. If you know the person, consider their personality and experience while reviewing their - code. Sometime it is possible with somebody to be more direct and terse, while + code. Sometimes it is possible with somebody to be more direct and terse, while other people require a more thorough explanation. - Avoid confrontational and authoritative language: The way we communicate has @@ -495,9 +495,9 @@ pitfalls a code reviewer should avoid. a problem in the code : "This operation is wrong. Please fix it." and "Doing this operation might result in an error, can you please review it?". The first one implies you made an error (confrontational), and - you should fix it (authority). The second suggest to review the code because + you should fix it (authority). The second suggests to review the code because there might be a mistake. Despite the message being the same, the recipient might - have a different reactions to it and impact on the quality of this work. This + have a different reaction to it and impact on the quality of this work. This general remark is valid for any comment. .. _merge_bot: diff --git a/docs/developer/snoop_example.rst b/docs/developer/snoop_example.rst index 33205761f576..b6cfee7c9299 100644 --- a/docs/developer/snoop_example.rst +++ b/docs/developer/snoop_example.rst @@ -190,10 +190,10 @@ The tool returns the following on standard output: This commands measures `100000` times the latency of the timer, that is the minimum time between two timing measurements. This yields an empirical distribution -on timings. The tools takes the 50th percentile (ie the median) of the empirical distribution +on timings. The tool takes the 50th percentile (ie the median) of the empirical distribution and returns the result: 25ns latency. This is reasonable. Since there's only one benchmark (with many samples), the standard deviation is by definition -zero. One could also run many benchmarks with less samples per benchmark: +zero. One could also run many benchmarks with fewer samples per benchmark: .. code-block:: shell diff --git a/docs/releases/version-9.rst b/docs/releases/version-9.rst index cc2f40a811f9..9f7351e050c8 100644 --- a/docs/releases/version-9.rst +++ b/docs/releases/version-9.rst @@ -32,7 +32,7 @@ Known Issues ------------ Regular but infrequent (a few times a day) spikes of RAM usage have -been noticed. If you run a node on hardware with less than 8Go of RAM +been noticed. If you run a node on hardware with less than 8 GB of RAM you should activate some swap to handle those spikes. Of course, swap may have a price in terms of performance. To not risk any slowdown at all, especially when baking on Mainnet, the safest option is to have -- GitLab From 909cf4bad15af1fa7f4bd3a8940e8dd2100281e4 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 13 Apr 2021 10:27:01 +0200 Subject: [PATCH 04/13] doc: move label build_from_sources to the right section --- docs/introduction/howtoget.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/introduction/howtoget.rst b/docs/introduction/howtoget.rst index e61dde017483..849f3c7c5046 100644 --- a/docs/introduction/howtoget.rst +++ b/docs/introduction/howtoget.rst @@ -160,7 +160,6 @@ executed by using ``./edo2net.sh client``, passing the needed arguments. Similar can be executed using ``./edo2net.sh admin-client``. -.. _build_from_sources: .. _building_with_opam: Building from sources via OPAM @@ -284,6 +283,7 @@ Identified situations where it will be more tricky are: The solution will be defined when delivering the first release with Rust dependencies. +.. _build_from_sources: .. _compiling_with_make: Setting up the development environment from scratch -- GitLab From 51b4fcdf41aa825341571c84c4c583aafa284f0e Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 6 Apr 2021 13:50:37 +0200 Subject: [PATCH 05/13] doc: fix left menu for "User doc" --- docs/index.rst | 8 ++++---- docs/user/history_modes.rst | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 4bd5f129e9bf..32d5960a42b2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -102,14 +102,14 @@ in the :ref:`introduction `. :caption: User documentation: user/key-management + user/node-configuration + user/snapshots + user/history_modes + user/multinetwork user/sandbox user/mockup user/proxy user/light - user/history_modes - user/snapshots - user/node-configuration - user/multinetwork user/various .. toctree:: diff --git a/docs/user/history_modes.rst b/docs/user/history_modes.rst index 5a4333df74b3..1790054bbeef 100644 --- a/docs/user/history_modes.rst +++ b/docs/user/history_modes.rst @@ -1,7 +1,7 @@ .. _history-modes: History modes -------------- +============= History modes allow a node to require less disk storage. Indeed, depending on the chosen history mode, some parts of the complete chain -- GitLab From 9e42a84bee86689bc526b72d1fb2357a15136fe3 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 7 Apr 2021 12:55:44 +0200 Subject: [PATCH 06/13] doc: replace link for fixes on 404 page --- docs/404.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/404.html b/docs/404.html index f03eef87c10a..7756d3ba29c7 100644 --- a/docs/404.html +++ b/docs/404.html @@ -77,7 +77,7 @@

The resource that you are attempting to access does not exist or you don't have the necessary permissions to view it.

Make sure the address is correct and that the page hasn't moved.

-

Please write to contact@nomadic-labs.com if you think this is a mistake.

+

Please consider creating a new Tezos/tezos issue if you think this is a mistake.

Go back