Merge pull request #114 from ethereumjs/first-rough-readme-update

README Update

PROJECT.md

@@ -1,5 +1,12 @@
 # ETHEREUMJS CLIENT - PROJECT SUMMARY
 
+NOTE:
+**This document is OUTDATED** and will be rewritten at some point in time. For the moment please refer to our communication channels on information on the state of client development.
+
+The EthereumJS Team, 2020-06-01
+
+---
+
 ## MAIN FOCUS
 
 Main goal of this project is to develop an Ethereum main net light client as well 

README.md

@@ -5,21 +5,16 @@
 [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
 [![Gitter](https://img.shields.io/gitter/room/ethereum/ethereumjs.svg?style=flat-square)](https://gitter.im/ethereum/ethereumjs)
 
-This is the work repository for the EthereumJS main chain client implementation project.
-This is a community project. See [Development Stages](./PROJECT.md#development-stages) for idea
-about the current project status, [issues](https://github.com/ethereumjs/ethereumjs-client/issues)
-for open issues and a project layout and read through [Community Project](./PROJECT.md#community-project)
-if you want to join.
+This is the work repository for the EthereumJS client project targetting both Node.js and the browser as a platform.
 
 See [Technical Guidelines](#technical-guidelines) if
 you directly want to dive into development info.
 
-Current development stage: ``CONCEPT ANALYSIS / EARLY DEVELOPMENT``
+Current development stage: ``EARLY DEVELOPMENT``
 
 # PROJECT SUMMARY
 
-For a summary of the project focus, some outline of a roadmap and information on the
-team and how to contribute/join see [this document](./PROJECT.md).
+Project summary from [this document](./PROJECT.md) is currently outdated. Please refer to our communication channels for some information on the current state of client development.
 
 # TECHNICAL GUIDELINES
 
@@ -66,7 +61,15 @@ for all output or something more targeted by listing the loggers like
 DEBUG=devp2p:rlpx,devp2p:eth,-babel [CLIENT_START_COMMAND]
 ```
 
-**Example 1: Light sync**
+## API
+
+[API Reference](./docs/API.md)
+
+See also this [diagram](./client_diagram.png) with an overview of the client structure together with the initialization and message flow.
+
+## EXAMPLES
+
+### Example 1: Light sync
 
 In this example, we will run two ethereumjs-clients. The first will be a fast sync client that
 will connect to the rinkeby network and start downloading the blockchain. The second will be a
@@ -97,7 +100,7 @@ ethereumjs --syncmode light --network rinkeby --datadir second --transports libp
 
 Notice that we have to run the second client on port 50506 using the ``multiaddrs=/ip4/0.0.0.0/tcp/50506`` libp2p option to avoid port conflicts.
 
-**Example 2: Light sync from within a browser**
+### Example 2: Light sync from within a browser
 
 In this example, we will again perform a light sync by connecting to the first client from above. However, this time we will connect directly to the first client from within a browser window using libp2p websockets.
 
@@ -123,44 +126,6 @@ ethereumjs.run({ network: 'rinkeby', syncmode: 'light', bootnodes: '/ip4/127.0.0
 
 That's it! Now, you should start seeing headers being downloaded to the local storage of your browser. Since IndexDB is being used, even if you close and re-open the browser window, the headers you'll already downloaded will be saved.
 
-## API
-
-[API Reference](./docs/API.md)
-
-## Environment / Ecosystem
-
-**EthereumJS Ecosystem**
-
-This project will be embedded in the EthereumJS ecosystem and many submodules already exist and
-can be used within the project, have a look e.g. at [ethereumjs-block](https://github.com/ethereumjs/ethereumjs-block), [ethereumjs-vm](https://github.com/ethereumjs/ethereumjs-vm), the
-[merkle-patricia-tree](https://github.com/ethereumjs/merkle-patricia-tree) or the
-[ethereumjs-devp2p](https://github.com/ethereumjs/ethereumjs-devp2p) implementation.
-
-To play well together within a client context, many sub module libraries need enhancements,
-e.g. to create a common logging context. There are also larger building blocks still
-missing, e.g. the [Node Discovery V5](https://github.com/ethereumjs/ethereumjs-devp2p/issues/19)
-p2p implementation being necessary for a proper working light client sync. Due to the distributed
-nature of EthereumJS there will be internal (to be done in this repo) and external issues
-(to be done in other EthereumJS repos) to be worked on.
-
-All (hopefully :-)) issues referring to the client implementation will be provided with a
-``ethereumjs-client`` label which should be discoverable with a label search on GitHub:
-
-- [Show external issues](https://github.com/search?utf8=%E2%9C%93&q=org%3Aethereumjs+label%3Aethereumjs-client&type=Issues&ref=advsearch&l=&l=)
-
-**Basic Environment**
-
-For library development the following basic environment is targeted. Some base requirements
-like the testing tool arise from the need of maintaining a somewhat unified EthereumJS environment
-where developers can switch between with some ease without the need to learn (too much) new
-tooling.
-
-- ``Node.js``
-- ``Javascript`` (ES6)
-- [Tape](https://github.com/substack/tape) for testing
-- [Istanbul/nyc](https://istanbul.js.org/) for test coverage
-- [standard.js](https://standardjs.com/) for linting/code formatting
-
 ## Design
 
 **Goals**
@@ -239,24 +204,16 @@ also make use of subclasses of the ``Fetcher`` class that help fetch headers and
 - ``Node`` [**In Progress**] Represents the top-level ethereum node, and is responsible for managing the lifecycle of included services.
 - ``RPCManager`` [**In Progress**] Implements an embedded JSON-RPC server to handle incoming RPC requests.
 
-## Contribution Guidelines
-**Communication** This is distributed team effort. If you plan to take on larger issues
-always pre-announce your work intention on the issue page and drop a short note on what
-you are planning to do. If there is no issue for the stuff you want to work on create one
-and describe the problem and outline the intended implementation before start working.
-
-**Branch Structure**
+## Environment / Ecosystem
 
-Development will take place via feature branches being merged against a protected ``master``
-branch. Always develop on branch also when being on your own fork, use meaningful branch
-names like ``new-debug-cl-option`` or ``fixed-this-really-annoying-bug``.
+**EthereumJS Ecosystem**
 
-**Testing**
+This project will be embedded in the EthereumJS ecosystem and many submodules already exist and
+can be used within the project, have a look e.g. at [ethereumjs-block](https://github.com/ethereumjs/ethereumjs-block), [ethereumjs-vm](https://github.com/ethereumjs/ethereumjs-vm), the
+[merkle-patricia-tree](https://github.com/ethereumjs/merkle-patricia-tree) or the
+[ethereumjs-devp2p](https://github.com/ethereumjs/ethereumjs-devp2p) implementation. Work needs to be done both within this repos and related libraries.
 
-No meaningful new PR will be accepted without associated tests (exceptions might be done on
-a case-by-case basis). Test coverage should not increase (significantly) by a new PR.
-You might also want to consider writing your tests first and then directly push them,
-since this would be a good starting point for discussing the scope/implementation of a feature.
+Related issues are labelled with the ``ethereumjs-client`` label, see [here](https://github.com/search?utf8=%E2%9C%93&q=org%3Aethereumjs+label%3Aethereumjs-client&type=Issues&ref=advsearch&l=&l=) for an org-wide search.
 
 ## EthereumJS