ethereum-optimism / specs

OP Stack Specifications
https://specs.optimism.io
Creative Commons Zero v1.0 Universal
90 stars 85 forks source link

Specs Layout Refactor #26

Open tynes opened 8 months ago

tynes commented 8 months ago

Right now it is difficult to contribute or consume the specs because of the way that they are laid out. It is not clear where to add new information and there isn't an easy way to know what functionality is associated with what network upgrade.

We should lay out the specs in a way where there is a set of topics and directories for each network upgrade. If a topic is changed as part of a network upgrade, we should include a markdown file named after the topic inside which includes the functionality specific for that network upgrade.

A simplified example below:

├── bedrock
│   ├── batcher.md
│   ├── derivation-pipeline.md
│   ├── predeploys.md
│   └── state-transition.md
├── canyon
│   └── state-transition.md
├── delta
│   └── span-batches.md
├── ecotone
│   └── predeploys.md
├── fjord
└── regolith
    └── state-transition.md
protolambda commented 7 months ago

I really like the per-hardfork categorization. It's consistent with the ethereum L1 consensus-specs, and makes it easy to extend specs incrementally. That said, a type of global overview-doc, with categorized features, and a type of mini-changelog with links to sections of the individual specs, would be really useful for navigation. Otherwise I would have to search 5 different state-transition.md docs until I find the state-transition feature change I am looking for.