Dec

.circleci/config.yml

@@ -0,0 +1,171 @@
+version: 2.1
+orbs:
+  utils: ethereum-optimism/[email protected]
+
+executors:
+  node20:
+    docker:
+      - image: cimg/node:20.11.1 # Prebuilt CircleCI image for Node.js 20.x
+    resource_class: medium # Adjust resource allocation as needed
+  ubuntu:
+    machine:
+      image: ubuntu-2204:current
+  rust:
+    docker:
+      - image: cimg/rust:1.75.0 # CircleCI's Rust Docker image
+    working_directory: ~/project
+
+commands:
+  setup-node:
+    steps:
+      - run:
+          name: Install Node.js (20.x) and pnpm
+          command: |
+            curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+            sudo apt-get install -y nodejs
+            npm install -g pnpm
+            pnpm --version
+      - restore_cache:
+          keys:
+            - v1-pnpm-cache-{{ checksum "pnpm-lock.yaml" }}
+      - run:
+          name: Install dependencies
+          command: npm install -g pnpm && pnpm install
+      - save_cache:
+          key: v1-pnpm-cache-{{ checksum "pnpm-lock.yaml" }}
+          paths:
+            - ~/.pnpm-store
+
+jobs:
+  algolia:
+    description: Create and upload Algolia search index
+    executor: ubuntu
+    steps:
+      - checkout
+      - setup-node
+      - run:
+          name: Create and upload index
+          command: |
+            # index:docs requires the following environment variables, coming from the algolia-search context
+            # ALGOLIA_APPLICATION_ID
+            # ALGOLIA_WRITE_API_KEY
+            # ALGOLIA_INDEX_NAME
+            pnpm run index:docs
+
+  breadcrumbs:
+    description: Check breadcrumbs in documentation
+    executor: ubuntu
+    steps:
+      - checkout
+      - setup-node
+      - run:
+          name: Run breadcrumb check
+          command: pnpm check-breadcrumbs
+  lint:
+    description: Lint Markdown files
+    executor: ubuntu
+    steps:
+      - checkout
+      - setup-node
+      - run:
+          name: Lint Markdown files
+          command: pnpm lint
+
+  links:
+    executor: rust
+    steps:
+      - checkout:
+          path: docs
+      - run:
+          name: Checkout lycheeverse/lychee
+          command: |
+            git clone https://github.com/lycheeverse/lychee.git lychee
+
+      - restore_cache:
+          keys:
+            - v1-rust-cache-{{ checksum "lychee/Cargo.lock" }}
+            - v1-rust-cache-
+
+      - run:
+          name: Build Lychee
+          command: |
+            cd lychee
+            cargo build --release
+
+      - save_cache:
+          key: v1-rust-cache-{{ checksum "lychee/Cargo.lock" }}
+          paths:
+            - ~/.cargo/registry
+            - ~/.cargo/git
+            - lychee/target
+
+      - run:
+          name: Run Lychee link checker
+          command: |
+            export PATH=$PATH:$HOME/project/lychee/target/release
+            cd docs
+            lychee --config ./lychee.toml --quiet "./pages"
+
+  developer-metrics:
+    description: Monthly Metrics Report
+    executor: ubuntu
+    parameters:
+      repo:
+        type: string
+        default: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
+    steps:
+      - utils/get-github-access-token:
+          private-key-str: GITHUB_APP_KEY
+          app-id: GITHUB_APP_ID
+          repo: << parameters.repo >>
+      - run:
+          name: Get Dates for Last Month
+          command: |
+            # Calculate the first day of the previous month
+            first_day=$(date -d "last month" +%Y-%m-01)
+
+
+            # Calculate the last day of the previous month
+            last_day=$(date -d "$first_day +1 month -1 day" +%Y-%m-%d)
+
+            # Export the last_month variable for subsequent steps
+            echo "export LAST_MONTH=${first_day}..${last_day}" >> $BASH_ENV
+      - utils/generate-issue-metrics-file:
+          SEARCH_QUERY: 'repo:ethereum-optimism/docs is:issue closed:${LAST_MONTH} -reason:\"not planned\" -label:monthly-report'
+          file-path: "./closed_issue_metrics.md"
+      - utils/create-github-issue-from-file:
+          repo: << parameters.repo >>
+          file-path: "./closed_issue_metrics.md"
+          issue-title: "${LAST_MONTH} metrics report for closed issues"
+          issue-labels: "monthly-report"
+          assignees: "sbvegan"
+      - utils/generate-issue-metrics-file:
+          SEARCH_QUERY: "repo:ethereum-optimism/docs is:pr created:${LAST_MONTH}"
+          file-path: "./pr_issue_metrics.md"
+      - utils/create-github-issue-from-file:
+          repo: << parameters.repo >>
+          file-path: "./pr_issue_metrics.md"
+          issue-title: "${LAST_MONTH} metrics report for opened prs"
+          issue-labels: "monthly-report"
+          assignees: "sbvegan"
+
+workflows:
+  merge-workflow:
+    jobs:
+      - algolia:
+          name: Algolia Index Update
+          context: algolia-search
+          filters:
+            branches:
+              only: main
+  pr-workflow:
+    jobs:
+      - breadcrumbs
+      - links
+      - lint
+  monthly-workflow:
+    when:
+      equal: [build_monthly, <<pipeline.schedule.name>>]
+    jobs:
+      - developer-metrics:
+          context: circleci-repo-docs

.coderabbit.yaml

@@ -4,18 +4,25 @@ reviews:
   high_level_summary: false
   poem: false
   review_status: false
-  collapse_walkthrough: false
+  collapse_walkthrough: true
+  changed_files_summary: false
   path_instructions:
     - path: "**/*.mdx"
       instructions: |
         "ALWAYS review Markdown content THOROUGHLY with the following criteria:
         - Use proper nouns in place of personal pronouns like 'We' and 'Our' to maintain consistency in communal documentation.
         - Avoid gender-specific language and use the imperative form.
-        - Monitor capitalization for emphasis. Use **bold** for prominence instead of all caps or italics.
+        - Monitor capitalization for emphasis. Avoid using all caps, italics, or bold for emphasis.
         - Ensure proper nouns are capitalized in sentences.
         - Apply the Oxford comma.
-        - Use proper title case for headers, buttons, tab names, page names, and links. Sentence case should be used for body content and short phrases, even in links.
+        - Use proper title case for buttons, tab names, page names, and links. Sentence case should be used for body content and short phrases, even in links.
         - Use correct spelling and grammar at all times (IMPORTANT).
+        - For H1, H2, and H3 headers:
+          1. Use sentence case, capitalizing only the first word.
+          2. Preserve the capitalization of proper nouns, technical terms, and acronyms as defined in the 'nouns.txt' file located in the root directory of the project.
+          3. Do not automatically lowercase words that appear in the 'nouns.txt' file, regardless of their position in the header.
+        - Flag any headers that seem to inconsistently apply these rules for manual review.
+        - When reviewing capitalization, always refer to the 'nouns.txt' file for the correct capitalization of proper nouns and technical terms specific to the project.
         "
   auto_review:
     enabled: true

.github/CODEOWNERS

@@ -1,2 +1,2 @@
 # Code reviewers
-* @squdgy @paulgnz
+* @squdgy @paulgnz

.github/ISSUE_TEMPLATE/docs_audit_results.md

@@ -0,0 +1,152 @@
+---
+name: Docs audit results
+about: Template for a formal technical documentation audits run by OP Labs
+title: "[2024 Q4 Audit] [page-path]"
+labels: ['docs-audit-2024-Q4', 'op-labs']
+---
+
+<!-- this template is intended for internal OP Labs usage -->
+
+## Description of the updates required
+
+<!-- Write a description of the current state of the page. -->
+
+### Acceptance criteria
+
+<!-- Definition of done for the assignee -->
+
+### Resources
+
+<!-- Supporting docs, points of contact, and any additional helpful info -->
+
+### Action items
+
+<!-- The process for working through this issue for example:
+1. Read through resources and meet with SME
+2. Write the first draft
+3. Share draft with SMEs and implement feedback
+4. Peer review
+5. Final SME review
+6. Publish -->
+
+## Github issue label criteria
+
+> Choose the appropriate github issue labels for each page.
+
+<details>
+
+<summary>Priority</summary>
+
+- `p-on-hold`: (Defer) Tasks that are currently not actionable due to various reasons like waiting for external inputs, dependencies, or resource constraints. These are reviewed periodically to decide if they can be moved to a more active status.
+- `p-low`: (Nice to do) Tasks that have minimal impact on core operations and no immediate deadlines. These tasks are often more about quality of life improvements rather than essential needs.
+- `p-medium`: (Could do) Tasks that need to be done but are less critical than high-priority tasks. These often improve processes or efficiency but can be postponed if necessary without immediate severe repercussions.
+- `p-high`: (Should do) Important tasks that contribute significantly to long-term goals but may not have an immediate deadline. Delaying these tasks could have considerable negative effects but are not as immediate as critical tasks.
+- `p-critical`: Tasks that have immediate deadlines or significant consequences if not completed on time. These are non-negotiable and often linked to core business functions or legal requirements. 
+</details>
+
+<details>
+
+<summary>T-shirt size</summary>
+
+- `s-XS`: (< 1 day) Very simple tasks that require minimal time and effort.
+- `s-S`: (few days) Tasks that are straightforward but require a bit more time to complete.
+- `s-M`: (1-2 weeks) Tasks that involve a moderate level of complexity and collaboration.
+- `s-L`: (several weeks) Complex tasks that require significant time investment and coordination across multiple teams. 
+- `s-XL`: (> 1 month) Very large and complex projects that involve extensive planning, execution, and testing. 
+</details>
+
+<details>
+
+<summary>Content evaluation</summary>
+- `a-delete`: don't need this page 
+- `a-duplicate`: some content lives elsewhere 
+- `a-minor`: needs small revisions 
+- `a-moderate`: needs moderate revisions 
+- `a-critical`: needs a lot of work
+</details>
+
+## MDX Metadata format
+
+> We will be adding better metadata to the header of each page. 
+> If I was actively searching for this page on google and this description was the search result, would I know it's the correct page?
+> Parse the component and feature tags to add.
+
+```mdx
+---
+title: "Your Title Here"
+tags: ["tag1", "tag2"]
+description: "A short description of the content."
+---
+```
+
+<details>
+<summary>Component tags</summary>
+
+```
+op-node
+op-geth
+op-reth
+op-erigon
+op-nethermind
+batcher
+standard-bridge
+sequencer
+l1-contracts
+l2-contracts
+precompiles
+predeploys
+preinstalls
+op-proposer
+op-challenger
+op-gov-token
+op-supervisor
+op-conductor
+fp-contracts
+cannon
+op-program
+asterisk
+kona
+superchain-registry
+supersim
+dev-console
+opsm
+mcp
+mcp-l2
+deputy-guardian
+liveness-guard
+dispute-mon
+op-beat
+op-signer
+monitorism
+blockspace-charters
+op-workbench
+kubernetes-infrastructure
+devops-tooling
+artifacts-packaging
+sequencer-in-a-box
+devnets
+performance-tooling
+peer-management-service
+proxyd
+zdd-service
+snapman
+security-tools
+superchain-ops
+op-deployer
+```
+</details>
+
+<details>
+<summary>Engineering tags</summary>
+
+```
+eng-platforms
+eng-growth
+eng-devx
+eng-protocol
+eng-proofs
+eng-evm
+eng-security
+```
+</details>
+

.github/ISSUE_TEMPLATE/general_docs_request.md

@@ -9,7 +9,7 @@ labels: 'community-request,documentation'
 <!-- please fill out the following the best to your ability and properly label the issue -->
 
 ## Brief Description of the Docs Request
-Write a clear and concise description of the docs request. For example, is the request related to an existing page or are you suggesting a brand new docs page?
+Write a clear and concise description of the docs request. For example, is the request related to an existing page or are you suggesting a brand-new docs page?
 
 ## Description of the Documentation You'd Like
 Explain what the final documentation page or pages should look like. Do you need a guide, tutorial, FAQ, troubleshooting page or more than one page? Do you have any source/content information to provide for the requested page(s)?