Skip to content

Commit bc814a0

Browse files
cpengillycpengilly
authored
Merge pull request #1408 from ethereum-optimism/metadata-test
2 parents 677531f + b334410 commit bc814a0

15 files changed

+1680
-25
lines changed

‎.circleci/config.yml

+12-1
Original file line numberDiff line numberDiff line change
@@ -66,14 +66,25 @@ jobs:
6666
command: pnpm check-breadcrumbs
6767

6868
lint:
69-
description: Lint Markdown files
69+
description: Lint Markdown files and validate metadata
7070
executor: ubuntu
7171
steps:
7272
- checkout
7373
- setup-node
74+
- run:
75+
name: Get changed files
76+
command: |
77+
if [ -n "$CIRCLE_PULL_REQUEST" ]; then
78+
PR_NUMBER=$(echo $CIRCLE_PULL_REQUEST | rev | cut -d'/' -f1 | rev)
79+
CHANGED_FILES=$(curl -s "https://api.github.com/repos/$CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME/pulls/$PR_NUMBER/files" | jq -r '.[].filename' | grep '\.mdx$' || true)
80+
echo "export CHANGED_FILES=\"$CHANGED_FILES\"" >> $BASH_ENV
81+
fi
7482
- run:
7583
name: Lint Markdown files
7684
command: pnpm lint
85+
- run:
86+
name: Validate metadata
87+
command: pnpm validate-pr-metadata
7788

7889
links:
7990
description: Check broken links in documentation

‎.coderabbit.yaml

+28
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,34 @@ reviews:
1010
- path: "**/*.mdx"
1111
instructions: |
1212
"ALWAYS review Markdown content THOROUGHLY with the following criteria:
13+
- First, check the frontmatter section at the top of the file:
14+
1. For regular pages, ensure ALL these fields are present and not empty:
15+
```yaml
16+
---
17+
title: [non-empty]
18+
lang: [non-empty]
19+
description: [non-empty]
20+
topic: [non-empty]
21+
personas: [non-empty array]
22+
categories: [non-empty array]
23+
content_type: [valid type]
24+
---
25+
```
26+
2. For landing pages (index.mdx or files with <Cards>), only these fields are required:
27+
```yaml
28+
---
29+
title: [non-empty]
30+
lang: [non-empty]
31+
description: [non-empty]
32+
topic: [non-empty]
33+
---
34+
```
35+
3. If any required fields are missing or empty, comment:
36+
'This file appears to be missing required metadata. You can fix this by running:
37+
```bash
38+
pnpm metadata-batch-cli:dry "path/to/this/file.mdx"
39+
```
40+
Review the changes, then run without :dry to apply them.'
1341
- Use proper nouns in place of personal pronouns like 'We' and 'Our' to maintain consistency in communal documentation.
1442
- Avoid gender-specific language and use the imperative form.
1543
- Monitor capitalization for emphasis. Avoid using all caps, italics, or bold for emphasis.

‎.eslintrc.js renamed to ‎.eslintrc.cjs

File renamed without changes.

‎dist/tsconfig.tsbuildinfo

+1
Large diffs are not rendered by default.

‎keywords.config.yaml

+237
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
# Metadata Configuration for Documentation
2+
metadata_rules:
3+
# PERSONA
4+
persona:
5+
required: true
6+
multiple: true
7+
min: 1
8+
validation_rules:
9+
- enum:
10+
- app-developer
11+
- node-operator
12+
- chain-operator
13+
- protocol-developer
14+
- partner
15+
description: "Must select at least one valid persona"
16+
17+
# CONTENT TYPE
18+
content_type:
19+
required: true
20+
multiple: false
21+
validation_rules:
22+
- enum:
23+
- tutorial # step-by-step instructions
24+
- landing-page # navigation and overview pages
25+
- guide # general how-to content and concept exlainers
26+
- reference # technical specifications and API docs
27+
- troubleshooting # problem-solution focused
28+
- notice # Technical updates: breaking changes, upgrades, deprecations
29+
- announcement # Community/Governance updates: new programs, initiatives
30+
description: "Must select exactly one content type"
31+
32+
# TOPIC
33+
topic:
34+
required: true
35+
multiple: false
36+
validation_rules:
37+
- pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
38+
description: "Must be kebab-case, derived from page title"
39+
examples: ["standard-bridge", "account-abstraction", "ecotone-upgrade"]
40+
- unique: true
41+
description: "Topic must be unique across all pages"
42+
- max_length: 100
43+
description: "Topic should be concise"
44+
45+
# CATEGORIES
46+
categories:
47+
required: true
48+
multiple: true
49+
min: 1
50+
max: 5
51+
validation_rules:
52+
- no_duplicates: true
53+
description: "Categories must not repeat"
54+
- no_metadata_overlap:
55+
fields: ["topic", "content_type", "persona"]
56+
description: "Categories cannot repeat values used in topic, content_type, or persona"
57+
values:
58+
# Data Availability Layer
59+
- eth-da
60+
- alt-da
61+
- permissionless-batch-submission
62+
- block-times
63+
64+
# Sequencing Layer
65+
- sequencer
66+
- sequencer-pbs
67+
- sequencer-decentralization
68+
- sequencer-in-a-box
69+
- op-batcher
70+
71+
# Derivation Layer
72+
- rollup-node
73+
- fault-proofs
74+
- fp-contracts
75+
- op-challenger
76+
- cannon
77+
- zk
78+
- op-workbench # Tool: derivation testing & simulation
79+
80+
# Execution Layer
81+
- op-geth
82+
- op-reth
83+
- op-erigon
84+
- op-nethermind
85+
- evm-equivalence
86+
- precompiles
87+
- predeploys
88+
- preinstalls
89+
- custom-gas-token
90+
- l2-contracts
91+
- dev-console # Tool: execution layer interaction
92+
93+
# Settlement Layer
94+
- l1-contracts
95+
- standard-bridge
96+
- teleportr
97+
- interop
98+
- interoperability
99+
- cross-chain-messaging
100+
- interoperable-assets
101+
- op-deployer # Tool: contract deployment
102+
- op-supervisor
103+
104+
# Governance Layer
105+
- security-council
106+
- op-token
107+
- blockspace-charters
108+
- retro-funding
109+
- revshare-enshrinement
110+
- superchain-registry
111+
112+
# Cross-layer Development Tools
113+
- supersim # Tests across multiple layers
114+
- devnets # Full-stack local environment
115+
- performance-tooling # Stack-wide performance testing
116+
- superchain-registry # Chain management across layers
117+
- l1-deployment-upgrade-tooling # Cross-layer deployment
118+
- l2-deployment-upgrade-tooling # Cross-layer deployment
119+
120+
# Chain Management (Cross-layer)
121+
- protocol
122+
- infrastructure
123+
- op-proposer
124+
- op-supervisor
125+
- op-conductor
126+
- op-signer
127+
- mcp
128+
- mcp-l2
129+
- upgrade-standard-chains-stage-1
130+
- launch-new-chains-stage-1
131+
- automated-pause
132+
- dispute-mon
133+
- monitorism
134+
- vertical-scaling
135+
136+
# Protocol Releases
137+
- granite
138+
- holocene
139+
- isthmus
140+
- canyon
141+
- delta
142+
- ecotone
143+
- fjord
144+
- network-upgrade
145+
- hard-fork
146+
147+
# Infrastructure & Operations
148+
- kubernetes-infrastructure
149+
- devops-tooling
150+
- artifacts-packaging
151+
- peer-management-service
152+
- proxyd
153+
- zdd-service
154+
- snapman
155+
- op-beat
156+
- security-monitoring-response
157+
- stability-monitoring
158+
- security
159+
160+
# Development Languages & SDKs
161+
- solidity
162+
- typescript
163+
- javascript
164+
- go
165+
- rust
166+
- python
167+
- foundry
168+
- hardhat
169+
- ethers
170+
- viem
171+
- web3js
172+
- wagmi
173+
174+
# Development Environments
175+
- local-devnet
176+
- testnet
177+
- mainnet
178+
179+
# TIMEFRAME
180+
timeframe:
181+
required_for:
182+
- announcement
183+
- notice
184+
required: false
185+
multiple: false
186+
validation_rules:
187+
# Component versions
188+
- pattern: ^(op-\w+|cannon)/v\d+\.\d+\.\d+$
189+
description: "Component releases must be in format component/vX.Y.Z"
190+
examples: ["op-node/v1.11.0", "op-batcher/v1.11.1"]
191+
192+
# Release candidates
193+
- pattern: ^(op-\w+)/v\d+\.\d+\.\d+-rc\.\d+$
194+
description: "Release candidates must be in format component/vX.Y.Z-rc.N"
195+
examples: ["op-node/v1.11.0-rc.2"]
196+
197+
# Alpha/Beta versions
198+
- pattern: ^(op-\w+|cannon)/v\d+\.\d+\.\d+-(alpha|beta)\.\d+$
199+
description: "Alpha/Beta releases must be in format component/vX.Y.Z-{alpha|beta}.N"
200+
examples: ["cannon/v1.4.0-alpha.1"]
201+
202+
# Season format
203+
- pattern: ^S[6-9]|S[1-9][0-9]+$
204+
description: "Season numbers must start with 'S' followed by a number 6 or greater"
205+
examples: ["S6", "S7", "S8", "S10"]
206+
207+
# Calendar year
208+
- pattern: ^20(2[4-9]|[3-9][0-9])$
209+
description: "Years must be 2024 or later"
210+
examples: ["2024", "2025", "2026"]
211+
212+
# Half year
213+
- pattern: ^20(2[4-9]|[3-9][0-9])H[1-2]$
214+
description: "Half years must be in format YYYYH1 or YYYYH2"
215+
examples: ["2024H1", "2024H2", "2025H1"]
216+
217+
# Quarter
218+
- pattern: ^20(2[4-9]|[3-9][0-9])Q[1-4]$
219+
description: "Quarters must be in format YYYYQ1-Q4"
220+
examples: ["2024Q1", "2024Q2", "2025Q3"]
221+
222+
# Month
223+
- pattern: ^20(2[4-9]|[3-9][0-9])-(0[1-9]|1[0-2])$
224+
description: "Months must be in format YYYY-MM"
225+
examples: ["2024-01", "2024-12", "2025-06"]
226+
227+
# Protocol upgrades
228+
- enum:
229+
- bedrock
230+
- canyon
231+
- delta
232+
- ecotone
233+
- fjord
234+
- granite
235+
- holocene
236+
- isthmus
237+
description: "Protocol upgrade names must match exactly"

‎notes/README.md

+6
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,10 @@ The Optimism Docs are internal docs to help you understand how the Optimism Docs
77
- [GitHub Actions](./actions.md)
88
- [Algolia Search](./algolia-search.md)
99
- [Lychee Link Checking](./lychee.md)
10+
- [Kapa AI Assistance](./kapa-ai-assistant.md)
11+
- [Breadcrumbs](./breadcrumbs.md)
12+
- [Content reuse](./content-reuse.md)
13+
- [Fix redirects](./fix-redirects.md)
14+
- [WIP callout](./wip-callout.md)
15+
- [Metadata batch update](./metadata-update.md)
1016
- [Public Resources Folder](./resources.md)

0 commit comments

Comments
 (0)