Merge pull request #805 from JBBianchi/feat-examples-readme-templating

Imports Validation Schemas into the Examples README during CI

.ci/examples-readme-hydration/.gitignore

@@ -0,0 +1 @@
+node_modules

.ci/examples-readme-hydration/index.js

@@ -0,0 +1,38 @@
+const fs = require('fs');
+const path = require('path');
+const YAML = require('yaml');
+
+const examplesPath = path.resolve(__dirname, '../../examples/');
+const readMeTemplatePath = path.resolve(examplesPath, 'README_TEMPLATE.md');
+const readMeOutputPath = path.resolve(examplesPath, 'README.md');
+const extractor = /<include file="(.*)" format="(.*)" \/>/g;
+const disclaimer = `<!--
+
+
+   !!! THIS IS A GENERATED FILE !!!
+   Please do not update this file but the TEMPLATE instead!
+
+   
+-->
+`;
+
+(async () => {
+  let readMe = await fs.promises.readFile(readMeTemplatePath, 'utf8');
+  const includes = readMe.matchAll(extractor);
+  for await(let include of includes) {
+    const fileName = include[1];
+    const format = include[2];
+    let fileContent = await fs.promises.readFile(path.resolve(examplesPath, fileName), 'utf8');
+    if (format === 'yaml') {
+      try {
+        const schema = JSON.parse(fileContent);
+        fileContent = YAML.stringify(schema);
+      }
+      catch(ex) {
+        console.error('Enable to parse JSON or convert it to YAML, output as it is.', ex);
+      }
+    }
+    readMe = readMe.replace(include[0], fileContent);
+  };
+  await fs.promises.writeFile(readMeOutputPath, disclaimer + readMe, { encoding: 'utf8', flag: 'w' });
+})();

.ci/examples-readme-hydration/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "examples-readme-hydration",
+  "version": "0.1.0",
+  "description": "Builds ./examples/README.md based on ./examples/README_TEMPLATE.md",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node ./index.js"
+  },
+  "keywords": ["cncf", "serverless", "workflow", "specification"],
+  "author": "CNCF Serverless Workflow Specification",
+  "license": "ISC",
+  "dependencies": {
+    "yaml": "^2.3.4"
+  }
+}

.github/workflows/examples-readme-check.yml

@@ -0,0 +1,21 @@
+name: Check examples README manual updates
+
+on:
+  pull_request:
+    paths:
+      - 'examples/README.md'
+
+jobs:
+  verification:
+    runs-on: ubuntu-latest
+    steps:
+      - if: contains(github.head_ref, 'automation-examples-readme')
+        name: pass
+        run: echo "The update is made by the bot, as expected."
+
+      - if: contains(github.head_ref, 'automation-examples-readme') == false
+        name: fail
+        run: |
+          echo "The file examples/README.md should not be manually edited !"
+          echo "Please update examples/README_TEMPLATE.md instead"
+          exit 1

.github/workflows/examples-readme-hydration.yml

@@ -0,0 +1,63 @@
+name: Examples README hydration
+
+on:
+  pull_request:
+    types:
+      - closed
+    branches: [ 'main']
+    paths:
+      - 'examples/**/*'
+      - '!examples/README.md'
+
+jobs:
+  build:
+    if: github.repository == 'serverlessworkflow/specification' &&  github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.BOT_PAT }}
+
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 21
+
+      - name: Import GPG key
+        id: import-gpg
+        uses: crazy-max/ghaction-import-gpg@v6
+        with:
+          gpg_private_key: ${{ secrets.BOT_GPG_PRIVATE_KEY }}
+          git_config_global: true
+          git_user_signingkey: true
+          git_commit_gpgsign: true
+          git_tag_gpgsign: true
+
+      - run: |
+          set -e
+
+          # Reset origin
+          git remote set-url origin https://${{ secrets.BOT_USERNAME }}:${{ secrets.BOT_PAT }}@github.com/${{ github.repository }}.git
+          git checkout ${{ github.ref_name }}
+          
+          # Create a new git branch
+          git checkout -b automation-examples-readme-${{ github.event.pull_request.number }}
+
+          # Install & run JS scripts
+          cd .ci/examples-readme-hydration/
+          npm ci
+          npm start
+
+          # Commit & push changes
+          git config user.name '${{ secrets.BOT_USERNAME }}'
+          git config user.email '${{ secrets.BOT_EMAIL }}'      
+          git commit -S -a -m 'Rebuilt examples README.md'
+          git push origin automation-examples-readme-${{ github.event.pull_request.number }}
+
+          # Create a PR on GH
+          gh pr create -B main -H automation-examples-readme-${{ github.event.pull_request.number }} --title '[From CI] Rebuilt examples README' --body 'Automatic hydration of examples README.md'
+        env:
+          GITHUB_TOKEN: ${{ secrets.BOT_PAT }}