Merge pull request #149 from 0xMiden/kbg/feat/v13-snapshot #12
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # ============================================================ | |
| # ARCHITECTURE NOTE: | |
| # This workflow ingests external repos and creates versioned snapshots. | |
| # | |
| # v0.4 Information Architecture: | |
| # - Design docs (miden-base, miden-vm, compiler, miden-node) → docs/design/ | |
| # - Builder docs (miden-tutorials, miden-client) → docs/builder/ | |
| # | |
| # Workflow responsibilities: | |
| # 1. Check out external repos at pinned refs | |
| # 2. Aggregate their docs into docs/ TEMPORARILY (v0.4 nested paths) | |
| # 3. Run `docusaurus docs:version` to snapshot into versioned_docs/ | |
| # 4. CLEAN UP docs/ (remove ingested folders) | |
| # 5. Commit versioned_docs/ snapshot | |
| # | |
| # After this workflow runs, docs/ returns to authored-only state. | |
| # The deploy workflow (deploy-docs.yml) also ingests for live "next" docs. | |
| # ============================================================ | |
| name: Cut Docs Version (global) | |
| on: | |
| # Manual trigger (preferred to start) | |
| workflow_dispatch: | |
| inputs: | |
| version_label: | |
| description: "Global version label (e.g. 0.12). If empty, use .release/release-manifest.yml" | |
| required: false | |
| # Optional per-repo overrides. If empty, use refs from manifest. | |
| miden_node_ref: { required: false } | |
| miden_vm_ref: { required: false } | |
| miden_base_ref: { required: false } | |
| miden_client_ref: { required: false } | |
| compiler_ref: { required: false } | |
| miden_tutorials_ref: { required: false } | |
| # Optional: auto-run when manifest changes (enable after you trust the flow) | |
| push: | |
| paths: | |
| - ".release/release-manifest.yml" | |
| permissions: | |
| contents: write | |
| jobs: | |
| cut: | |
| runs-on: ubuntu-latest | |
| env: | |
| REPO_NODE: 0xMiden/miden-node | |
| REPO_VM: 0xMiden/miden-vm | |
| REPO_BASE: 0xMiden/miden-base | |
| REPO_CLIENT: 0xMiden/miden-client | |
| REPO_COMPILER: 0xMiden/compiler | |
| REPO_TUTORIALS: 0xMiden/miden-tutorials | |
| steps: | |
| - name: Checkout aggregator | |
| uses: actions/checkout@v4 | |
| with: { fetch-depth: 0 } | |
| - name: Setup Node | |
| uses: actions/setup-node@v4 | |
| with: { node-version: 20, cache: "npm" } | |
| - name: Install deps | |
| run: npm ci | |
| - name: Parse release manifest (and merge with manual inputs) | |
| id: manifest | |
| run: | | |
| node - <<'NODE' | |
| const fs = require('fs'); | |
| const path = '.release/release-manifest.yml'; | |
| const YAML = require('yaml'); | |
| const read = (p) => fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : ''; | |
| const m = YAML.parse(read(path) || '{}') || {}; | |
| // Prefer manual inputs if provided; else manifest; else fallback to "main" | |
| const getRef = (input, manifestVal) => input && input.trim() ? input.trim() : (manifestVal || 'main'); | |
| const inputs = { | |
| version_label: process.env.INPUT_VERSION_LABEL || '' | |
| }; | |
| const refs = m.refs || {}; | |
| // Build outputs | |
| const out = { | |
| version_label: inputs.version_label || (m.version || '').trim(), | |
| miden_node_ref: getRef(process.env.INPUT_MIDEN_NODE_REF, refs['miden-node']), | |
| miden_vm_ref: getRef(process.env.INPUT_MIDEN_VM_REF, refs['miden-vm']), | |
| miden_base_ref: getRef(process.env.INPUT_MIDEN_BASE_REF, refs['miden-base']), | |
| miden_client_ref: getRef(process.env.INPUT_MIDEN_CLIENT_REF, refs['miden-client']), | |
| compiler_ref: getRef(process.env.INPUT_COMPILER_REF, refs['compiler']), | |
| miden_tutorials_ref: getRef(process.env.INPUT_MIDEN_TUTORIALS_REF, refs['miden-tutorials']), | |
| }; | |
| if (!out.version_label) { | |
| console.error('No version label provided (inputs.version_label empty and no "version" in release-manifest).'); | |
| process.exit(1); | |
| } | |
| // Emit outputs | |
| for (const [k,v] of Object.entries(out)) { | |
| console.log(`::set-output name=${k}::${v}`); | |
| } | |
| NODE | |
| - name: Validate refs exist | |
| run: | | |
| set -e | |
| validate() { | |
| repo="$1"; ref="$2" | |
| echo "Validating $repo @ $ref" | |
| git ls-remote "https://github.com/$repo" "$ref" | grep -q . || { | |
| echo "ERROR: Ref '$ref' not found in $repo" | |
| exit 1 | |
| } | |
| } | |
| validate "${REPO_NODE}" "${{ steps.manifest.outputs.miden_node_ref }}" | |
| validate "${REPO_VM}" "${{ steps.manifest.outputs.miden_vm_ref }}" | |
| validate "${REPO_BASE}" "${{ steps.manifest.outputs.miden_base_ref }}" | |
| validate "${REPO_CLIENT}" "${{ steps.manifest.outputs.miden_client_ref }}" | |
| validate "${REPO_COMPILER}" "${{ steps.manifest.outputs.compiler_ref }}" | |
| validate "${REPO_TUTORIALS}" "${{ steps.manifest.outputs.miden_tutorials_ref }}" | |
| - name: Checkout sources at validated refs | |
| run: | | |
| set -e | |
| checkout_ref() { | |
| repo="$1"; ref="$2"; path="$3" | |
| echo "Checking out $repo @ $ref → $path" | |
| git clone "https://github.com/$repo" "$path" | |
| (cd "$path" && git fetch --depth 1 origin "$ref" && git checkout "$ref") | |
| } | |
| checkout_ref "${REPO_NODE}" "${{ steps.manifest.outputs.miden_node_ref }}" vendor/miden-node | |
| checkout_ref "${REPO_VM}" "${{ steps.manifest.outputs.miden_vm_ref }}" vendor/miden-vm | |
| checkout_ref "${REPO_BASE}" "${{ steps.manifest.outputs.miden_base_ref }}" vendor/miden-base | |
| checkout_ref "${REPO_CLIENT}" "${{ steps.manifest.outputs.miden_client_ref }}" vendor/miden-client | |
| checkout_ref "${REPO_COMPILER}" "${{ steps.manifest.outputs.compiler_ref }}" vendor/compiler | |
| checkout_ref "${REPO_TUTORIALS}" "${{ steps.manifest.outputs.miden_tutorials_ref }}" vendor/miden-tutorials | |
| # ============================================================ | |
| # v0.4 IA: Aggregate into nested structure (TEMPORARY) | |
| # This content is cleaned up after versioning (see "Clean up" step below) | |
| # ============================================================ | |
| - name: Aggregate docs into v0.4 IA structure | |
| run: | | |
| echo "Aggregating vendor docs into v0.4 IA structure..." | |
| # Clean directories that will be re-synced (v0.4 nested paths) | |
| rm -rf docs/design/miden-base docs/design/miden-vm docs/design/miden-node docs/design/compiler | |
| rm -rf docs/builder/tutorials docs/builder/client | |
| # Design docs → docs/design/* | |
| if [ -d "vendor/miden-base/docs/src" ]; then | |
| mkdir -p docs/design/miden-base | |
| cp -r vendor/miden-base/docs/src/* docs/design/miden-base/ | |
| echo "Synced miden-base → docs/design/miden-base" | |
| fi | |
| if [ -d "vendor/miden-vm/docs/src" ]; then | |
| mkdir -p docs/design/miden-vm | |
| cp -r vendor/miden-vm/docs/src/* docs/design/miden-vm/ | |
| echo "Synced miden-vm → docs/design/miden-vm" | |
| fi | |
| if [ -d "vendor/miden-node/docs/external/src" ]; then | |
| mkdir -p docs/design/miden-node | |
| cp -r vendor/miden-node/docs/external/src/* docs/design/miden-node/ | |
| echo "Synced miden-node → docs/design/miden-node" | |
| fi | |
| if [ -d "vendor/compiler/docs/external/src" ]; then | |
| mkdir -p docs/design/compiler | |
| cp -r vendor/compiler/docs/external/src/* docs/design/compiler/ | |
| echo "Synced compiler → docs/design/compiler" | |
| fi | |
| # Builder docs → docs/builder/* | |
| if [ -d "vendor/miden-tutorials/docs/src" ]; then | |
| mkdir -p docs/builder/tutorials | |
| cp -r vendor/miden-tutorials/docs/src/* docs/builder/tutorials/ | |
| echo "Synced miden-tutorials → docs/builder/tutorials" | |
| fi | |
| if [ -d "vendor/miden-client/docs/src" ]; then | |
| mkdir -p docs/builder/client | |
| cp -r vendor/miden-client/docs/src/* docs/builder/client/ | |
| echo "Synced miden-client → docs/builder/client" | |
| fi | |
| echo "Content aggregation complete. Final docs structure:" | |
| ls -la docs/ | |
| echo "Design subdirs:" | |
| ls -la docs/design/ || true | |
| echo "Builder subdirs:" | |
| ls -la docs/builder/ || true | |
| - name: Cut version snapshot | |
| run: | | |
| VERSION="${{ steps.manifest.outputs.version_label }}" | |
| echo "Creating Docusaurus version: $VERSION" | |
| npm run docusaurus -- docs:version "$VERSION" | |
| # CRITICAL: Clean up docs/ to maintain canonical-source architecture | |
| # docs/ must only contain authored content (builder/, design/ landing pages) | |
| # All ingested content lives in versioned_docs/ after versioning | |
| - name: Clean up (delete vendor and ingested docs) | |
| run: | | |
| rm -rf vendor | |
| # Clean v0.4 nested paths | |
| rm -rf docs/design/miden-base | |
| rm -rf docs/design/miden-vm | |
| rm -rf docs/design/miden-node | |
| rm -rf docs/design/compiler | |
| rm -rf docs/builder/tutorials | |
| rm -rf docs/builder/client | |
| - name: Commit snapshots | |
| run: | | |
| if ! git diff --quiet; then | |
| git config user.name "github-actions[bot]" | |
| git config user.email "41898282+github-actions[bot]@users.noreply.github.com" | |
| git add -A | |
| git commit -m "docs: cut version ${{ steps.manifest.outputs.version_label }}" | |
| git push | |
| else | |
| echo "No changes to commit." | |
| fi |