From 204472c0a139c061bc99b1c4fa560854db7abb91 Mon Sep 17 00:00:00 2001 From: Mark Tyneway Date: Tue, 20 Aug 2024 12:50:24 -0700 Subject: [PATCH] readme: update information on why specs We need a clear explanation about why specs and how to think about them. Opening this PR for feedback. --- README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.md b/README.md index 26c506cce..a15113ede 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,23 @@ Please chat with us on the [discussion board](https://github.com/ethereum-optimi We welcome your contributions. Read through [CONTRIBUTING.md](./CONTRIBUTING.md) for a general overview of the contributing process for this repository. +### How to Think about Specs + +The specs process is a schelling point for where core developers go to modify the OP Stack. A spec serves multiple purposes: +- Ensures that we know what we are building before we build it +- Helps code reviewers and auditors understand what the behavior is supposed to be +- Enables multiple implementations + +Some guidelines for writing a good spec: +- Thoroughly describe the interfaces that other projects may interact with +- Include a light description of the problem that is being solved and the rationale but the majority of this should be recorded during the design doc phase +- Describe things in terms of state machines and invariants +- It should be clear that it solves the problem at hand + +What is the difference between the specs and the [design docs](https://github.com/ethereum-optimism/design-docs)? +- The design docs describe why and the specs describe how. +- The design doc phase should be complete before the specs process is complete + ### Dependencies **Rust Toolchain**