doc: update README (#8731)

* doc: update README

Updates the development and release process, adds missing entries to
the directory structure, fixes links, and adds a table of contents.

* docs: clarifications from review

* docs: link to node releases

* doc: update with op-contracts convention

* doc: update TOC

* chore: typographic cleanup

README.md

@@ -7,6 +7,25 @@
   <br />
 </div>
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [What is Optimism?](#what-is-optimism)
+- [Documentation](#documentation)
+- [Specification](#specification)
+- [Community](#community)
+- [Contributing](#contributing)
+- [Security Policy and Vulnerability Reporting](#security-policy-and-vulnerability-reporting)
+- [Directory Structure](#directory-structure)
+- [Development and Release Process](#development-and-release-process)
+  - [Overview](#overview)
+  - [Production Releases](#production-releases)
+  - [Development branch](#development-branch)
+- [License](#license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## What is Optimism?
 
 [Optimism](https://www.optimism.io/) is a project dedicated to scaling Ethereum's technology and expanding its ability to coordinate people from across the world to build effective decentralized economies and governance systems. The [Optimism Collective](https://app.optimism.io/announcement) builds open-source software for running L2 blockchains and aims to address key governance and economic challenges in the wider cryptocurrency ecosystem. Optimism operates on the principle of **impact=profit**, the idea that individuals who positively impact the Collective should be proportionally rewarded with profit. **Change the incentives and you change the world.**
@@ -16,7 +35,7 @@ In this repository, you'll find numerous core components of the OP Stack, the de
 ## Documentation
 
 - If you want to build on top of OP Mainnet, refer to the [Optimism Documentation](https://docs.optimism.io)
-- If you want to build your own OP Stack based blockchain, refer to the [OP Stack Guide](https://docs.optimism.io/stack/getting-started)
+- If you want to build your own OP Stack based blockchain, refer to the [OP Stack Guide](https://docs.optimism.io/stack/getting-started), and make sure to understand this repository's [Development and Release Process](#development-and-release-process)
 
 ## Specification
 
@@ -31,7 +50,7 @@ Governance discussion can also be found on the [Optimism Governance Forum](https
 
 Read through [CONTRIBUTING.md](./CONTRIBUTING.md) for a general overview of the contributing process for this repository.
 Use the [Developer Quick Start](./CONTRIBUTING.md#development-quick-start) to get your development environment set up to start working on the Optimism Monorepo.
-Then check out the list of [Good First Issues](https://github.com/ethereum-optimism/optimism/labels/D-good-first-issue) to find something fun to work on!
+Then check out the list of [Good First Issues](https://github.com/ethereum-optimism/optimism/issues?q=is:open+is:issue+label:D-good-first-issue) to find something fun to work on!
 Typo fixes are welcome; however, please create a single commit with all of the typo fixes & batch as many fixes together in a PR as possible. Spammy PRs will be closed.
 
 ## Security Policy and Vulnerability Reporting
@@ -44,8 +63,8 @@ The Optimism Immunefi program offers up to $2,000,042 for in-scope critical vuln
 
 <pre>
 ├── <a href="./docs">docs</a>: A collection of documents including audits and post-mortems
-├── <a href="./op-bindings">op-bindings</a>: Go bindings for Bedrock smart contracts.
 ├── <a href="./op-batcher">op-batcher</a>: L2-Batch Submitter, submits bundles of batches to L1
+├── <a href="./op-bindings">op-bindings</a>: Go bindings for Bedrock smart contracts.
 ├── <a href="./op-bootnode">op-bootnode</a>: Standalone op-node discovery bootnode
 ├── <a href="./op-chain-ops">op-chain-ops</a>: State surgery utilities
 ├── <a href="./op-challenger">op-challenger</a>: Dispute game challenge agent
@@ -56,83 +75,78 @@ The Optimism Immunefi program offers up to $2,000,042 for in-scope critical vuln
 ├── <a href="./op-program">op-program</a>: Fault proof program
 ├── <a href="./op-proposer">op-proposer</a>: L2-Output Submitter, submits proposals to L1
 ├── <a href="./op-service">op-service</a>: Common codebase utilities
+├── <a href="./op-ufm">op-ufm</a>: Simulations for monitoring end-to-end transaction latency
 ├── <a href="./op-wheel">op-wheel</a>: Database utilities
+├── <a href="./ops">ops</a>: Various operational packages
 ├── <a href="./ops-bedrock">ops-bedrock</a>: Bedrock devnet work
 ├── <a href="./packages">packages</a>
 │   ├── <a href="./packages/chain-mon">chain-mon</a>: Chain monitoring services
 │   ├── <a href="./packages/common-ts">common-ts</a>: Common tools for building apps in TypeScript
-│   ├── <a href="./packages/contracts-ts">contracts-ts</a>: ABI and Address constants
 │   ├── <a href="./packages/contracts-bedrock">contracts-bedrock</a>: Bedrock smart contracts
+│   ├── <a href="./packages/contracts-ts">contracts-ts</a>: ABI and Address constants
 │   ├── <a href="./packages/core-utils">core-utils</a>: Low-level utilities that make building Optimism easier
-│   └── <a href="./packages/sdk">sdk</a>: provides a set of tools for interacting with Optimism
-└── <a href="./proxyd">proxyd</a>: Configurable RPC request router and proxy
+│   ├── <a href="./packages/fee-estimation">fee-estimation</a>: Tools for estimating gas on OP chains
+│   ├── <a href="./packages/sdk">sdk</a>: provides a set of tools for interacting with Optimism
+│   └── <a href="./packages/web3js-plugin">web3js-plugin</a>: Adds functions to estimate L1 and L2 gas
+├── <a href="./proxyd">proxyd</a>: Configurable RPC request router and proxy
+├── <a href="./specs">specs</a>: Specs of the rollup starting at the Bedrock upgrade
+└── <a href="./ufm-test-services">ufm-test-services</a>: Runs a set of tasks to generate metrics
 </pre>
 
-## Branching Model
-
-### Active Branches
-
-| Branch          | Status                                                                           |
-| --------------- | -------------------------------------------------------------------------------- |
-| [master](https://github.com/ethereum-optimism/optimism/tree/master/)                   | Accepts PRs from `develop` when intending to deploy to production.                  |
-| [develop](https://github.com/ethereum-optimism/optimism/tree/develop/)                 | Accepts PRs that are compatible with `master` OR from `release/X.X.X` branches.                    |
-| release/X.X.X                                                                          | Accepts PRs for all changes, particularly those not backwards compatible with `develop` and `master`. |
+## Development and Release Process
 
 ### Overview
 
-This repository generally follows [this Git branching model](https://nvie.com/posts/a-successful-git-branching-model/).
-Please read the linked post if you're planning to make frequent PRs into this repository.
-
-### Production branch
-
-The production branch is `master`.
-The `master` branch contains the code for latest "stable" releases.
-Updates from `master` **always** come from the `develop` branch.
-
-### Development branch
-
-The primary development branch is [`develop`](https://github.com/ethereum-optimism/optimism/tree/develop/).
-`develop` contains the most up-to-date software that remains backwards compatible with the latest experimental [network deployments](https://community.optimism.io/docs/useful-tools/networks/).
-If you're making a backwards compatible change, please direct your pull request towards `develop`.
+Please read this section if you're planning to fork this repository, or make frequent PRs into this repository.
 
-**Changes to contracts within `packages/contracts-bedrock/src` are usually NOT considered backwards compatible and SHOULD be made against a release candidate branch**.
-Some exceptions to this rule exist for cases in which we absolutely must deploy some new contract after a release candidate branch has already been fully deployed.
-If you're changing or adding a contract and you're unsure about which branch to make a PR into, default to using the latest release candidate branch.
-See below for info about release candidate branches.
+### Production Releases
 
-### Release candidate branches
+Production releases are always tags, versioned as `<component-name>/v<semver>`.
+For example, an `op-node` release might be versioned as `op-node/v1.1.2`, and  smart contract releases might be versioned as `op-contracts/v1.0.0`.
+Release candidates are versioned in the format `op-node/v1.1.2-rc.1`.
+We always start with `rc.1` rather than `rc`.
 
-Branches marked `release/X.X.X` are **release candidate branches**.
-Changes that are not backwards compatible and all changes to contracts within `packages/contracts-bedrock/src` MUST be directed towards a release candidate branch.
-Release candidates are merged into `develop` and then into `master` once they've been fully deployed.
-We may sometimes have more than one active `release/X.X.X` branch if we're in the middle of a deployment.
-See table in the **Active Branches** section above to find the right branch to target.
+For contract releases, refer to the GitHub release notes for a given release, which will list the specific contracts being released—not all contracts are considered production ready within a release, and many are under active development.
 
-## Releases
+Tags of the form `v<semver>`, such as `v1.1.4`, indicate releases of all Go code only, and **DO NOT** include smart contracts.
+This naming scheme is required by Golang.
+In the above list, this means these `v<semver` releases contain all `op-*` components, and exclude all `contracts-*` components.
 
-### Changesets
+`op-geth` embeds upstream geth’s version inside it’s own version as follows: `vMAJOR.GETH_MAJOR GETH_MINOR GETH_PATCH.PATCH`.
+Basically, geth’s version is our minor version.
+For example if geth is at `v1.12.0`, the corresponding op-geth version would be `v1.101200.0`.
+Note that we pad out to three characters for the geth minor version and two characters for the geth patch version.
+Since we cannot left-pad with zeroes, the geth major version is not padded.
 
-We use [changesets](https://github.com/changesets/changesets) to mark packages for new releases.
-When merging commits to the `develop` branch you MUST include a changeset file if your change would require that a new version of a package be released.
+See the [Node Software Releases](https://docs.optimism.io/builders/node-operators/releases) page of the documentation for more information about releases for the latest node components.
+The full set of components that have releases are:
 
-To add a changeset, run the command `pnpm changeset` in the root of this monorepo.
-You will be presented with a small prompt to select the packages to be released, the scope of the release (major, minor, or patch), and the reason for the release.
-Comments within changeset files will be automatically included in the changelog of the package.
+- `chain-mon`
+- `ci-builder`
+- `ci-builder`
+- `indexer`
+- `op-batcher`
+- `op-contracts`
+- `op-challenger`
+- `op-heartbeat`
+- `op-node`
+- `op-proposer`
+- `op-ufm`
+- `proxyd`
+- `ufm-metamask`
 
-### Triggering Releases
+All other components and packages should be considered development components only and do not have releases.
 
-Releases can be triggered using the following process:
-
-1. Create a PR that merges the `develop` branch into the `master` branch.
-2. Wait for the auto-generated `Version Packages` PR to be opened (may take several minutes).
-3. Change the base branch of the auto-generated `Version Packages` PR from `master` to `develop` and merge into `develop`.
-4. Create a second PR to merge the `develop` branch into the `master` branch.
+### Development branch
 
-After merging the second PR into the `master` branch, packages will be automatically released to their respective locations according to the set of changeset files in the `develop` branch at the start of the process.
-Please carry this process out exactly as listed to avoid `develop` and `master` falling out of sync.
+The primary development branch is [`develop`](https://github.com/ethereum-optimism/optimism/tree/develop/).
+`develop` contains the most up-to-date software that remains backwards compatible with the latest experimental [network deployments](https://community.optimism.io/docs/useful-tools/networks/).
+If you're making a backwards compatible change, please direct your pull request towards `develop`.
 
-**NOTE**: PRs containing changeset files merged into `develop` during the release process can cause issues with changesets that can require manual intervention to fix.
-It's strongly recommended to avoid merging PRs into develop during an active release.
+**Changes to contracts within `packages/contracts-bedrock/src` are usually NOT considered backwards compatible.**
+Some exceptions to this rule exist for cases in which we absolutely must deploy some new contract after a tag has already been fully deployed.
+If you're changing or adding a contract and you're unsure about which branch to make a PR into, default to using a feature branch.
+Feature branches are typically used when there are conflicts between 2 projects touching the same code, to avoid conflicts from merging both into `develop`.
 
 ## License