From 71556b94188b938893bd624651080b5cdb90946f Mon Sep 17 00:00:00 2001 From: Benjamin Canou Date: Tue, 20 Feb 2018 09:58:51 +0100 Subject: [PATCH] Update the README With: Arthur B --- CHANGES.alphanet | 230 --------------------- README.md | 31 +++ docs/Makefile | 5 +- docs/README.rst | 5 +- docs/conf.py | 4 + docs/index.rst | 40 +++- docs/introduction/alphanet.rst | 2 + docs/introduction/alphanet_changes.md | 1 - docs/introduction/alphanet_changes.rst | 231 +++++++++++++++++++++- README.rst => docs/introduction/howto.rst | 14 +- 10 files changed, 312 insertions(+), 251 deletions(-) delete mode 100644 CHANGES.alphanet create mode 100644 README.md delete mode 120000 docs/introduction/alphanet_changes.md mode change 120000 => 100644 docs/introduction/alphanet_changes.rst rename README.rst => docs/introduction/howto.rst (96%) diff --git a/CHANGES.alphanet b/CHANGES.alphanet deleted file mode 100644 index 606b333f4..000000000 --- a/CHANGES.alphanet +++ /dev/null @@ -1,230 +0,0 @@ -Alphanet changelog -================== - -For the next reset ------------------- - -[Alpha] - -- Do not allow revealing the same endorsement twice. - -- Tez values now have 6 decimals instead of two. The syntax used by - the client and Michelson use comma separators every three - digits, before and after the dot. For instance, 3 million tez and 10 - µtez is written `3,000,000.000,01`. The syntax in JSON is the raw - amount in µtez, either as a number without decimals or as a decimal - string, for the same example we would get `"3000000000010"`. - -[Node] - -- Rewrite of the RPC library to handle content types, to enable binary - RPCs and proper HTTP verbs. The next version will probably break the - HTTP API. - -- Now that we don't use the git backend anymore, we finally updated - the context hashing function from SHA1 to Blake2B. - -[Michelson] - -- Set a maximum type size, as a simple solution to avoid some type - checker abuses where types can grow exponentially. - -- Annotations are now correctly handled by macros. - -[Build] - -- Split the code base into separate OPAM packages. - - -Reset 2017-11-20 ------------------- - -[Alphanet] - -- Limit the number of faucet operations at 5 per block. - -[Client] - -- Autocomplete scripts for bash. - -- Smart contracts are now non spendable by default. - -- Add a debug command to list invalid blocks. - -[Node] - -- Prevent potential stack overflow in validation. - -- Fix concurrency issue where operations were cleared from - memory before being used. - -- Continue background work on the multipass validator: - cleanup and document data structures, better logging - of resource requests, enhance requests for the same piece - of data to multiple peers, split the code in smaller - simpler components. - -- P2p: fix issue with data greater than 2^16 bytes - -- Irmin: use an experimental LevelDB backend - -[Build] - -- Refactor the economic protocol amendment code. Protocols are - now compiled to functors, taking the type signature of their - runtime environment as parameter. This simplifies the - dependencies, and will allow third party developpers to - instanciate economic protocols in other contexts than the node. - -- Switch from Makefiles to jbuilder, yay! - -- Rename (hopefully) all occurences of "mining" into "baking". - -[Michelson] - - - Introduce Micheline, the (now independent) IR of Michelson. - The parser and printer should now be used on their own, outside - of the client or node. - -- Implement a basic semantics of annotations. - The typechecker now propagates annotations on types througout the - code, and tagging instructions with an annotation allows the - programmer to reannotate the element produced by the instruction. - The emacs mode displays propagated annotations. - -- Add a version of `ITER` that takes a static code block and expects - a colletion on the initial stack, and works like a `LOOP`, pushing - the element of the collection one at a time on the stack. This is - like `REDUCE` but using a static code block instead of a dynamic - lambda. In the same vein, `MAP` can take a code block. - -- Add `LOOP_LEFT` that uses a different type for the accumulator and - the return value. Continues while the top of the stack is `Left 'a` - and stops on `Right 'b`. - -- Change timestamps to be arbitrary precision relative integers. - -- Add `SIZE` on lists. - -Reset 2017-11-17 ----------------- - -[Node] - -- P2p: fix issue with data greater then 2^16 bytes -- Irmin: restore usage `git-repack`... (mistakenly removed) - -Reset 2017-10-13 ----------------- - -[Client] - - - Fix missing nonce revelation at end of cycle. - - New command line analyzer and better help pages. - -[Node] - - - Various small fixes and error message enhancements. - -[Alphanet] - - - Use older leveldb-1.18 as upgrade to the newer version made the - node crash. - -[Michelson] - - - Split the `key` type into `key` and `key_hash` to - prevent an error raised when using an unrevealed key. - -Reset 2017-09-21 ----------------- - -[Node] - -- fix a performance issue in roll storage - -[Doc] - -- improve scripts and documentations on how to run sandboxed node - or a local private network - -[Client] - -- add an option `-log-requests`. All RPC requests and responses to the - node are logged on `stderr`. - -[Michelson] - - - Split the `key` type into `key` and `key_hash` to - prevent an error raised when using an unrevealed key. - -Reset 2017-08-10 ----------------- - -This update includes changes in the on-disk state of the node and in -the format of blocks and operations. It thus requires a chain reset. - -Main changes includes: - -[Doc] - -- The documentation previously available on the Slack channel is now - available at: - - https://raw.githubusercontent.com/tezos/tezos/alphanet/README.md - -- The `alphanet` branch of the github repository is now automaticaly - synchronized with `alphanet` docker image. And the latest version of - the `alphanet.sh` is available at: - - https://raw.githubusercontent.com/tezos/tezos/alphanet/scripts/alphanet.sh - - No need to update manually though, the script auto-update itself - when running: - - ./alphanet.sh restart - - Or: - - ./alphanet.sh update_script - - -[Michelson] - -- minor language enhancements, mostly resulting from the feedback of - Milo's daily challenge: - - http://www.michelson-lang.com/ - -- the alphanet scripts now understands a container: prefix wherever a - file: prefix is accepted, temporarily copying the file into the - container, and the emacs-mode is aware of that - -[Node] - -- Operations now include a block hash in their header. Such an - operation could only be included in a successor of this block. - -- The economics protocol now refuses blocks that includes an operation - forged more than 64 blocks in the past. As any constants set by the - economic protocol, it is amendable by a vote. - -- Header of blocks now includes a hash of the "context" that result - from its validation. This is currently the SHA1 of the git commit, - but this will be changed in a near future for a safer cryptographic - hash. - -- The node does not need anymore to maintain a full index of the - operation to operate. This greatly reduce the memory and disk usage. - -- The node now builds against `irmin.1.3` where some of our code and - optimizations were upstreamed. We were previously stuck to - irmin.0.12. - - -[CI] - -- This is not directly visible in the alphanet, but our CI - infrastrucre is now ready for open development. - More about that soon (or later). - diff --git a/README.md b/README.md new file mode 100644 index 000000000..c7ab52229 --- /dev/null +++ b/README.md @@ -0,0 +1,31 @@ +Tezos +===== + +Tezos is a distributed consensus platform with meta-consensus +capability. Tezos not only comes to consensus about the state of its ledger, +like Bitcoin or Ethereum. It also attempts to come to consensus about how the +protocol and the nodes should adapt and upgrade. + + - Developer documentation is available online at http://doc.tzalpha.net + - The page https://www.tezos.com/ contains more information about the + project, even though it is frozen in time due to external reasons + - All development now happens on Gitlab at https://gitlab.com/tezos/tezos + +The Tezos Alpha (test) network has been live and open since February 2017. + + - More information on joining the Alphanet at http://doc.tzalpha.net/introduction/alphanet.html + - Several community built block explorers are available: + - https://ostez.com + - https://tzscan.io + - https://tezos.id + - https://tezoschain.io + - A few community run websites collect useful Tezos links: + - https://tezos.help + - https://tezos.rocks + - There is a matrix channel *Tezos* that you can join via https://riot.im/app/#/room/#tezos:matrix.org + - There is a *#tezos* channel on *freenode* that is reserved for technical discussions + - There is also a community FAQ at https://github.com/tezoscommunity/faq + +The source code of Tezos is currently under exclusive copyright of +Dynamic Ledger Solutions, and will be open sourced under the MIT +license when the main network lunches. diff --git a/docs/Makefile b/docs/Makefile index 6067bb042..877094f99 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -10,14 +10,11 @@ all: html linkcheck linkcheck: $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" -introduction/readme.rst: ../README.rst - sed 's/TEZOS/How to build and run/' $< > $@ - .PHONY: help Makefile # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -html: Makefile introduction/readme.rst +html: Makefile @$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) clean: diff --git a/docs/README.rst b/docs/README.rst index ada4b01ce..2e3f7713a 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -2,10 +2,13 @@ Building documentation locally ****************************** +The documenation is available online at `doc.tzalpha.net `_, +always up to date with master on `Gitlab `_. + Building instructions --------------------- -To build the documentaion, you can use the main Makefile target ``doc-html`` +To build the documentation, you can use the main Makefile target ``doc-html`` .. code:: bash diff --git a/docs/conf.py b/docs/conf.py index 2d531de3f..f7ab824a2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -173,3 +173,7 @@ texinfo_documents = [ author, 'Tezos', 'One line description of project.', 'Miscellaneous'), ] + +# -- Ignore fragments in linkcheck + +linkcheck_anchors = False diff --git a/docs/index.rst b/docs/index.rst index cc2b72d7d..96f8ffa15 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,14 +3,48 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to Tezos's documentation! -================================= + +Welcome to the Tezos Developper Documentation! +============================================== + +Tezos is a distributed consensus platform with meta-consensus +capability. Tezos not only comes to consensus about the state of its ledger, +like Bitcoin or Ethereum. It also attempts to come to consensus about how the +protocol and the nodes should adapt and upgrade. + + - Developer documentation is available online at http://doc.tzalpha.net + - The page https://www.tezos.com/ contains more information about the + project, even though it is frozen in time due to external reasons + - All development now happens on Gitlab at https://gitlab.com/tezos/tezos + +The Tezos Alpha (test) network has been live and open since February 2017. + + - More information on joining the Alphanet at :ref:`here `. + - Several community built block explorers are available: + + - http://ostez.com + - http://tzscan.io + - https://tezos.id + - https://tezoschain.io + +- A few community run websites collect useful Tezos links: + + - http://www.tezos.help + - https://tezos.rocks + + - There is a matrix channel *Tezos* that you can join `here `_. + - There is a *#tezos* channel on *freenode* that is reserved for technical discussions + - There is also a community FAQ at https://github.com/tezoscommunity/faq + +The source code of Tezos is currently under exclusive copyright of +Dynamic Ledger Solutions, and will be open sourced under the MIT +license when the main network lunches. .. toctree:: :maxdepth: 2 :caption: Introduction: - introduction/readme + introduction/howto introduction/contributing .. toctree:: diff --git a/docs/introduction/alphanet.rst b/docs/introduction/alphanet.rst index 37a6d0156..93e493027 100644 --- a/docs/introduction/alphanet.rst +++ b/docs/introduction/alphanet.rst @@ -1,3 +1,5 @@ +.. _alphanet: + Participating in the Alphanet ============================= diff --git a/docs/introduction/alphanet_changes.md b/docs/introduction/alphanet_changes.md deleted file mode 120000 index 2bcab7ec4..000000000 --- a/docs/introduction/alphanet_changes.md +++ /dev/null @@ -1 +0,0 @@ -../../CHANGES.alphanet \ No newline at end of file diff --git a/docs/introduction/alphanet_changes.rst b/docs/introduction/alphanet_changes.rst deleted file mode 120000 index 2bcab7ec4..000000000 --- a/docs/introduction/alphanet_changes.rst +++ /dev/null @@ -1 +0,0 @@ -../../CHANGES.alphanet \ No newline at end of file diff --git a/docs/introduction/alphanet_changes.rst b/docs/introduction/alphanet_changes.rst new file mode 100644 index 000000000..606b333f4 --- /dev/null +++ b/docs/introduction/alphanet_changes.rst @@ -0,0 +1,230 @@ +Alphanet changelog +================== + +For the next reset +------------------ + +[Alpha] + +- Do not allow revealing the same endorsement twice. + +- Tez values now have 6 decimals instead of two. The syntax used by + the client and Michelson use comma separators every three + digits, before and after the dot. For instance, 3 million tez and 10 + µtez is written `3,000,000.000,01`. The syntax in JSON is the raw + amount in µtez, either as a number without decimals or as a decimal + string, for the same example we would get `"3000000000010"`. + +[Node] + +- Rewrite of the RPC library to handle content types, to enable binary + RPCs and proper HTTP verbs. The next version will probably break the + HTTP API. + +- Now that we don't use the git backend anymore, we finally updated + the context hashing function from SHA1 to Blake2B. + +[Michelson] + +- Set a maximum type size, as a simple solution to avoid some type + checker abuses where types can grow exponentially. + +- Annotations are now correctly handled by macros. + +[Build] + +- Split the code base into separate OPAM packages. + + +Reset 2017-11-20 +------------------ + +[Alphanet] + +- Limit the number of faucet operations at 5 per block. + +[Client] + +- Autocomplete scripts for bash. + +- Smart contracts are now non spendable by default. + +- Add a debug command to list invalid blocks. + +[Node] + +- Prevent potential stack overflow in validation. + +- Fix concurrency issue where operations were cleared from + memory before being used. + +- Continue background work on the multipass validator: + cleanup and document data structures, better logging + of resource requests, enhance requests for the same piece + of data to multiple peers, split the code in smaller + simpler components. + +- P2p: fix issue with data greater than 2^16 bytes + +- Irmin: use an experimental LevelDB backend + +[Build] + +- Refactor the economic protocol amendment code. Protocols are + now compiled to functors, taking the type signature of their + runtime environment as parameter. This simplifies the + dependencies, and will allow third party developpers to + instanciate economic protocols in other contexts than the node. + +- Switch from Makefiles to jbuilder, yay! + +- Rename (hopefully) all occurences of "mining" into "baking". + +[Michelson] + + - Introduce Micheline, the (now independent) IR of Michelson. + The parser and printer should now be used on their own, outside + of the client or node. + +- Implement a basic semantics of annotations. + The typechecker now propagates annotations on types througout the + code, and tagging instructions with an annotation allows the + programmer to reannotate the element produced by the instruction. + The emacs mode displays propagated annotations. + +- Add a version of `ITER` that takes a static code block and expects + a colletion on the initial stack, and works like a `LOOP`, pushing + the element of the collection one at a time on the stack. This is + like `REDUCE` but using a static code block instead of a dynamic + lambda. In the same vein, `MAP` can take a code block. + +- Add `LOOP_LEFT` that uses a different type for the accumulator and + the return value. Continues while the top of the stack is `Left 'a` + and stops on `Right 'b`. + +- Change timestamps to be arbitrary precision relative integers. + +- Add `SIZE` on lists. + +Reset 2017-11-17 +---------------- + +[Node] + +- P2p: fix issue with data greater then 2^16 bytes +- Irmin: restore usage `git-repack`... (mistakenly removed) + +Reset 2017-10-13 +---------------- + +[Client] + + - Fix missing nonce revelation at end of cycle. + - New command line analyzer and better help pages. + +[Node] + + - Various small fixes and error message enhancements. + +[Alphanet] + + - Use older leveldb-1.18 as upgrade to the newer version made the + node crash. + +[Michelson] + + - Split the `key` type into `key` and `key_hash` to + prevent an error raised when using an unrevealed key. + +Reset 2017-09-21 +---------------- + +[Node] + +- fix a performance issue in roll storage + +[Doc] + +- improve scripts and documentations on how to run sandboxed node + or a local private network + +[Client] + +- add an option `-log-requests`. All RPC requests and responses to the + node are logged on `stderr`. + +[Michelson] + + - Split the `key` type into `key` and `key_hash` to + prevent an error raised when using an unrevealed key. + +Reset 2017-08-10 +---------------- + +This update includes changes in the on-disk state of the node and in +the format of blocks and operations. It thus requires a chain reset. + +Main changes includes: + +[Doc] + +- The documentation previously available on the Slack channel is now + available at: + + https://raw.githubusercontent.com/tezos/tezos/alphanet/README.md + +- The `alphanet` branch of the github repository is now automaticaly + synchronized with `alphanet` docker image. And the latest version of + the `alphanet.sh` is available at: + + https://raw.githubusercontent.com/tezos/tezos/alphanet/scripts/alphanet.sh + + No need to update manually though, the script auto-update itself + when running: + + ./alphanet.sh restart + + Or: + + ./alphanet.sh update_script + + +[Michelson] + +- minor language enhancements, mostly resulting from the feedback of + Milo's daily challenge: + + http://www.michelson-lang.com/ + +- the alphanet scripts now understands a container: prefix wherever a + file: prefix is accepted, temporarily copying the file into the + container, and the emacs-mode is aware of that + +[Node] + +- Operations now include a block hash in their header. Such an + operation could only be included in a successor of this block. + +- The economics protocol now refuses blocks that includes an operation + forged more than 64 blocks in the past. As any constants set by the + economic protocol, it is amendable by a vote. + +- Header of blocks now includes a hash of the "context" that result + from its validation. This is currently the SHA1 of the git commit, + but this will be changed in a near future for a safer cryptographic + hash. + +- The node does not need anymore to maintain a full index of the + operation to operate. This greatly reduce the memory and disk usage. + +- The node now builds against `irmin.1.3` where some of our code and + optimizations were upstreamed. We were previously stuck to + irmin.0.12. + + +[CI] + +- This is not directly visible in the alphanet, but our CI + infrastrucre is now ready for open development. + More about that soon (or later). + diff --git a/README.rst b/docs/introduction/howto.rst similarity index 96% rename from README.rst rename to docs/introduction/howto.rst index 8948f74e3..994c87caa 100644 --- a/README.rst +++ b/docs/introduction/howto.rst @@ -1,12 +1,5 @@ -TEZOS -===== - -Tezos is a distributed consensus platform with meta-consensus -capability. Tezos not only comes to consensus about state, like BTC or -ETH. It also comes to consensus about how the protocol and the nodes -should adapt and upgrade. - -See https://www.tezos.com/ for more information about the project. +How to build and run +==================== Build instructions ------------------ @@ -48,8 +41,7 @@ While building the dependencies, ``opam`` is able to handle correctly the OCaml libraries but it is not always able to handle all external C libraries we depend on. On most system, it is able to suggest a call to the system package manager but it currently does not handle version -check. In particular, the ``libsodium-dev`` packages on Ubuntu is too -old for building Tezos, we rely on version ``1.0.11`` at least. +check. At last, compile the project: