Feat/release part1

.github/workflows/deploy.yaml

@@ -38,7 +38,14 @@ jobs:
       - name: Install JS dependencies
         run: npm ci
 
+      - name: Assemble versioned docs from releases
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: node scripts/assemble-versions.js
+
       - name: Build docs
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: npm run build:docs
 
       - name: Upload artifact
@@ -65,7 +72,7 @@ jobs:
         id: deployment
         uses: actions/deploy-pages@v4
 
-  deploy-spec:
+  deploy-spec-main:
     runs-on: ubuntu-latest
     needs: build
     permissions:
@@ -80,10 +87,10 @@ jobs:
         run: |
           git config user.name "GitHub Actions Bot"
           git config user.email "<>"
-      - name: Deploy assembled spec
+      - name: Deploy assembled spec (main, unstamped)
         run: |
-          git checkout -b assembled-spec
+          git checkout -b assembled-spec-main
           git add -f openrpc.json
           git add -f refs-openrpc.json
-          git commit -m "assemble openrpc.json"
-          git push -fu origin assembled-spec
+          git commit -m "assemble openrpc.json from main@${GITHUB_SHA::7}"
+          git push -fu origin assembled-spec-main

.github/workflows/publish-spec.yaml

@@ -0,0 +1,37 @@
+name: Publish stamped spec branch
+
+on:
+  release:
+    types: [ published ]
+
+permissions:
+  contents: write
+
+jobs:
+  publish-spec:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download stamped spec from release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          gh release download "$TAG" \
+            --repo "$GITHUB_REPOSITORY" \
+            --pattern openrpc.json \
+            --pattern refs-openrpc.json \
+            --clobber
+      - name: setup git config
+        run: |
+          git config user.name "GitHub Actions Bot"
+          git config user.email "<>"
+      - name: Deploy assembled spec (stamped release)
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          git checkout -b assembled-spec
+          git add -f openrpc.json
+          git add -f refs-openrpc.json
+          git commit -m "release ${TAG}"
+          git push -fu origin assembled-spec

.github/workflows/release.yaml

@@ -0,0 +1,122 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to (re)release, e.g. v1.2.0"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build-release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.inputs.tag || github.ref }}
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version: ^1.26
+        id: go
+
+      - name: Build the spec
+        run: make build
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+
+      - name: Install JS dependencies
+        run: npm ci
+
+      - name: Stamp spec version from tag
+        env:
+          TAG: ${{ github.event.inputs.tag || github.ref_name }}
+        run: npm run spec:set-version -- --version "$TAG"
+
+      - name: Build docs
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: npm run build:docs
+
+      - name: Snapshot versioned docs
+        env:
+          TAG: ${{ github.event.inputs.tag || github.ref_name }}
+        run: |
+          VER="${TAG#v}"
+          npx docusaurus docs:version:api "$VER"
+          tar -czf "docs-snapshot-${TAG}.tar.gz" \
+            "api_versioned_docs/version-${VER}" \
+            "api_versioned_sidebars/version-${VER}-sidebars.json"
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build
+
+      - name: Upload openrpc spec
+        uses: actions/upload-artifact@v4
+        with:
+          name: openrpc-spec
+          path: |
+            openrpc.json
+            refs-openrpc.json
+
+      - name: Upload docs snapshot
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-snapshot
+          path: docs-snapshot-*.tar.gz
+
+  deploy-pages:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build-release
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+  github-release:
+    runs-on: ubuntu-latest
+    needs: build-release
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: openrpc-spec
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs-snapshot
+
+      - name: Create draft GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.event.inputs.tag || github.ref_name }}
+        run: |
+          gh release create "$TAG" \
+            --repo "$GITHUB_REPOSITORY" \
+            --title "$TAG" \
+            --draft \
+            --generate-notes \
+            openrpc.json refs-openrpc.json "docs-snapshot-${TAG}.tar.gz"

.github/workflows/sync-release-notes.yaml

@@ -0,0 +1,52 @@
+name: Sync release notes to repo
+
+on:
+  release:
+    types: [ published, edited ]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to sync (e.g. v1.2.0)"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+
+      - name: Sync release note
+        id: sync
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          INPUT_TAG: ${{ github.event.inputs.tag }}
+        run: node scripts/sync-release-note.js
+
+      - name: Open / update PR
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          base: main
+          branch: release-notes/${{ steps.sync.outputs.slug }}
+          commit-message: "docs: release notes for ${{ steps.sync.outputs.tag }}"
+          title: "docs: release notes for ${{ steps.sync.outputs.tag }}"
+          body: |
+            Mirrors the GitHub Release for **${{ steps.sync.outputs.tag }}** into `docs-releases/`.
+
+            Source: ${{ steps.sync.outputs.html_url }}
+
+            After this PR is merged, edit the markdown directly via PR for any future fixes — no need to republish the GitHub Release.
+          add-paths: |
+            docs-releases/**
+          delete-branch: true

.github/workflows/test-deploy.yaml

@@ -26,7 +26,18 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Test build website
+      - name: Test build website (no versions)
         run: |
           npm run build:spec
           npm run build:docs
+
+      - name: Test versioned build (synthesized snapshot)
+        run: |
+          npm run build:spec
+          npm run docs:copy
+          npx docusaurus docs:version:api 0.0.0-test
+          npm run build:docusaurus
+          test -d build/next || (echo "build/next missing — current docs not under /next when versions present" && exit 1)
+          test -f build/index.html || (echo "build/index.html missing — latest version landing not built at root" && exit 1)
+          grep -q '0.0.0-test' build/index.html || (echo "version dropdown not wired into latest landing" && exit 1)
+          echo "versioned build OK: /next + / (latest=0.0.0-test) both present"

.gitignore

@@ -1,4 +1,5 @@
 **/node_modules
+docs-api/api
 **/.cache
 build/
 openrpc.json
@@ -10,3 +11,7 @@ schema.json
 .docusaurus/
 .DS_Store
 .tool-versions
+api_versioned_docs/
+api_versioned_sidebars/
+api_versions.json
+docs-snapshot-*.tar.gz