maintenance[monorepo]: first pass update to README (#1106)

* maintenance[monorepo]: first pass update to README Doing some relatively minor updates to the README just to clean things up a bit. * replying to review comments
ethereum-optimism · Jun 16, 2021 · b74b052 · b74b052
1 parent 0b91df4
commit b74b052
Showing 1 changed file with 95 additions and 42 deletions.
diff --git a/README.md b/README.md
@@ -1,14 +1,20 @@
-# <h1 align="center"> Optimism Monorepo </h1>
+<p align="center">
+    <img src="https://user-images.githubusercontent.com/14298799/122151157-0b197500-ce2d-11eb-89d8-6240e3ebe130.png" width=280>
+<p>
 
-**Monorepo implementing the Optimistic Ethereum protocol**
+# <h1 align="center"> The Optimism Monorepo </h1>
 
 [![Github Actions](https://github.com/ethereum-optimism/optimism/workflows/typescript%20/%20contracts/badge.svg)](https://github.com/ethereum-optimism/optimism/actions/workflows/ts-packages.yml?query=branch%3Amaster)
 [![Github Actions](https://github.com/ethereum-optimism/optimism/workflows/integration/badge.svg)](https://github.com/ethereum-optimism/optimism/actions/workflows/integration.yml?query=branch%3Amaster)
 [![Github Actions](https://github.com/ethereum-optimism/optimism/workflows/geth%20unit%20tests/badge.svg)](https://github.com/ethereum-optimism/optimism/actions/workflows/geth.yml?query=branch%3Amaster)
 
+## TL;DR
+
+This is the primary place where [Optimism](https://optimism.io) works on stuff related to [Optimistic Ethereum](https://research.paradigm.xyz/optimism).
+
 ## Documentation
 
-Extensive documentation is available [here](http://community.optimism.io/docs/)
+Extensive documentation is available [here](http://community.optimism.io/docs/).
 
 ## Directory Structure
 
@@ -26,65 +32,54 @@ Extensive documentation is available [here](http://community.optimism.io/docs/)
 * [`ops`](./ops): Contains Dockerfiles for containerizing each service involved in the protocol,
 as well as a docker-compose file for bringing up local testnets easily
 
-## Quickstart
+## Development Quick Start
 
-### Installation
+### Setup
 
-Dependency management is done using `yarn`.
+Clone the repository, open it, and install dependencies:
 
 ```bash
 git clone git@github.com:ethereum-optimism/optimism.git
 cd optimism
-yarn
+yarn install
 ```
 
-After installing the dependencies, you must also build them so that the typescript
-is compiled down to javascript:
+### Building the TypeScript packages
 
-```bash
-yarn build
-```
-
-When changing branches, be sure to clean the repo before building.
+To build all of the [TypeScript packages](./packages), run:
 
 ```bash
 yarn clean
+yarn build
 ```
 
-### Unit tests
-
-All tests are run in parallel using `lerna`:
-
-```bash
-yarn test
-```
-
-When you want to run tests only for packages that have changed since `master` (or any other branch)
-you can run `yarn lerna run test --parallel --since master`
-
-### Integration Tests
+Packages compiled when on one branch may not be compatible with packages on a different branch.
+**You should recompile all packages whenever you move from one branch to another.**
+Use the above commands to recompile the packages.
 
-#### Running the integration tests
+### Building the rest of the system
 
-The integration tests first require bringing up the Optimism stack. This is done via
-a Docker Compose network. For better performance, we also recommend enabling Docker
-BuildKit
+If you want to run an Optimistic Ethereum node OR **if you want to run the integration tests**, you'll need to build the rest of the system.
 
-```bash
+```
 cd ops
-export COMPOSE_DOCKER_CLI_BUILD=1
+export COMPOSE_DOCKER_CLI_BUILD=1 # these environment variables significantly speed up build time
 export DOCKER_BUILDKIT=1
 docker-compose build
-cd ../integration-tests
-yarn build:integration
-yarn test:integration
 ```
 
-#### Locally testing and re-building specific services
-
-If you want to make changes to any of the containers, you'll have to bring one down,
-rebuild it, and then bring it back up.
-
+This will build the following containers:
+* [`builder`](https://hub.docker.com/r/ethereumoptimism/builder): used to build the TypeScript packages
+* [`l1_chain`](https://hub.docker.com/r/ethereumoptimism/hardhat): simulated L1 chain using hardhat-evm as a backend
+* [`deployer`](https://hub.docker.com/r/ethereumoptimism/deployer): process that deploys L1 smart contracts to the L1 chain
+* [`dtl`](https://hub.docker.com/r/ethereumoptimism/data-transport-layer): service that indexes transaction data from the L1 chain
+* [`l2geth`](https://hub.docker.com/r/ethereumoptimism/l2geth): L2 geth node running in Sequencer mode
+* [`verifier`](https://hub.docker.com/r/ethereumoptimism/go-ethereum): L2 geth node running in Verifier mode
+* [`relayer`](https://hub.docker.com/r/ethereumoptimism/message-relayer): helper process that relays messages between L1 and L2
+* [`batch_submitter`](https://hub.docker.com/r/ethereumoptimism/batch-submitter): service that submits batches of Sequencer transactions to the L1 chain
+* [`integration_tests`](https://hub.docker.com/r/ethereumoptimism/integration-tests): integration tests in a box
+
+If you want to make a change to a container, you'll need to take it down and rebuild it.
 For example, if you make a change in l2geth:
 
 ```bash
@@ -104,17 +99,75 @@ docker-compose build -- builder batch_submitter
 docker-compose start batch_submitter
 ```
 
+Source code changes can have an impact on more than one container.
+**If you're unsure about which containers to rebuild, just rebuild them all**:
+
+```
+cd ops
+docker-compose down
+docker-compose build
+docker-compose up
+```
+
+Finally, **if you're running into weird problems and nothing seems to be working**, run:
+
+```
+cd optimism
+yarn clean
+yarn build
+cd ops
+docker-compose down -v
+docker-compose build
+docker-compose up
+```
+
+#### Viewing docker container logs
 By default, the `docker-compose up` command will show logs from all services, and that
 can be hard to filter through. In order to view the logs from a specific service, you can run:
 
 ```
 docker-compose logs --follow <service name>
 ```
-### Static analysis
 
-To run `slither` locally in `./packages/contracts` do
+### Running tests
+
+Before running tests: **follow the above instructions to get everything built.**
+
+#### Running unit tests
+
+Run unit tests for all packages in parallel via:
+
+```bash
+yarn test
+```
+
+To run unit tests for a specific package:
+
+```bash
+cd packages/package-to-test
+yarn test
+```
+
+#### Running integration tests
+
+Follow above instructions for building the whole stack.
+Build and run the integration tests:
 
+```bash
+cd integration-tests
+yarn build:integration
+yarn test:integration
 ```
+
+## Additional Reference Material
+### Running contract static analysis
+
+We perform static analysis with [`slither`](https://github.com/crytic/slither).
+You must have Python 3.x installed to run `slither`.
+To run `slither` locally, do:
+
+```bash
+cd packages/contracts
 pip3 install slither-analyzer
 yarn test:slither
 ```