5.x cherry picks

.github/CODEOWNERS

@@ -0,0 +1 @@
+./.github/ @recrwplay

.github/dependabot.yml

@@ -0,0 +1,16 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+    groups:
+      prod-dependencies:
+        dependency-type: "production"
+      dev-dependencies:
+        dependency-type: "development"

.github/workflows/docs-branch-checks.yml

@@ -0,0 +1,53 @@
+# This is an example of the docs-pr.yml workflow available from the recrwplay org
+name: "Verify Branch"
+
+on:
+  # push:
+  #   branches:
+    #   - dev
+  # schedule:
+    # - cron:  '00 16 * * *'
+  workflow_dispatch:
+    inputs:
+      html:
+        description: 'Generate HTML'
+        type: boolean
+        required: false
+        default: true
+      links:
+        description: 'Check links'
+        type: boolean
+        required: false
+        default: true
+      lint:
+        description: 'Lint docs'
+        type: boolean
+        required: false
+        default: false
+
+jobs:
+
+  docs-build:
+    if: ${{ inputs.html || github.event_name == 'push' }}
+    name: Generate HTML
+    uses: neo4j/docs-tools/.github/workflows/[email protected]
+    with:
+      retain-artifacts: 14
+      deploy-id: 0
+
+  docs-verify:
+    name: Verify HTML
+    needs: docs-build
+    uses: neo4j/docs-tools/.github/workflows/[email protected]
+
+  docs-links:
+    if: ${{ inputs.links || github.event_name == 'push' }}
+    name: Check links
+    needs: docs-build
+    uses: neo4j/docs-tools/.github/workflows/[email protected]
+
+  docs-lint:
+    if: ${{ inputs.lint || github.event_name == 'push' }}
+    name: Lint docs
+    uses: neo4j/docs-tools/.github/workflows/[email protected]
+

.github/workflows/docs-deploy-surge.yml

@@ -1,67 +1,128 @@
 # Use this starter workflow to deploy HTML generated by Antora to surge.sh
 # Docs are published at <org>-<repo>-<deployid>.surge.sh
-# By default, this workflow runs on completion of a workflow called "Verify PR"
-# This workflow expects the triggering workflow to generate an artifact called "docs"
 
+# By default, this workflow runs on completion of a workflow called "Verify docs PR"
+
+# This workflow expects the triggering workflow to generate an artifact called "docs"
 # - update the reference to "docs" and "docs.zip" in this workflow if your triggering workflow generates an artifact with a different name
-name: "Deploy to surge"
+
+# change to force workflow with no changelog
+
+name: "Deploy docs preview"
 
 on:
   workflow_run:
-    workflows: ["Verify PR"]
+    workflows: ["Verify docs PR"]
     types:
       - completed
 
 jobs:
   publish-docs:
+    # Uncomment this if statement to deploy only when the PR builds cleanly
     # if: github.event.workflow_run.conclusion == 'success'
 
     runs-on: ubuntu-latest
 
     steps:
       - name: "Download built documentation"
-        uses: actions/[email protected]
+        uses: actions/github-script@v7
+        env:
+          RUN_ID: ${{ github.event.workflow_run.id }}
+          WORKSPACE: ${{ github.workspace }}
         with:
           script: |
             var artifacts = await github.rest.actions.listWorkflowRunArtifacts({
                owner: context.repo.owner,
                repo: context.repo.repo,
-               run_id: ${{ github.event.workflow_run.id }},
+               run_id: ${{ env.RUN_ID }},
             });
-            var matchArtifact = artifacts.data.artifacts.filter((artifact) => {
+
+            var matchArtifactDocs = artifacts.data.artifacts.filter((artifact) => {
               return artifact.name == "docs"
             })[0];
-            var download = await github.rest.actions.downloadArtifact({
+            var downloadDocs = await github.rest.actions.downloadArtifact({
                owner: context.repo.owner,
                repo: context.repo.repo,
-               artifact_id: matchArtifact.id,
+               artifact_id: matchArtifactDocs.id,
                archive_format: 'zip',
             });
             var fs = require('fs');
-            fs.writeFileSync('${{ github.workspace }}/docs.zip', Buffer.from(download.data));
-
-      - run: unzip docs.zip
-
+            fs.writeFileSync('${{ env.WORKSPACE }}/docs.zip', Buffer.from(downloadDocs.data));
+
+            var matchArtifactChangelog = artifacts.data.artifacts.filter((artifact) => {
+              return artifact.name == "changelog"
+            })[0];
+            var downloadChangelog = await github.rest.actions.downloadArtifact({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              artifact_id: matchArtifactChangelog.id,
+              archive_format: 'zip',
+            });
+            fs.writeFileSync('${{ env.WORKSPACE }}/changelog.zip', Buffer.from(downloadChangelog.data));
+
+      - id: unzip-docs
+        run: unzip docs.zip
+
+      - id: get-top-dir
+        run: |
+          root=$(ls -d */index.html | sed -r 's/(.*)\/index\.html/\1/')
+          echo "top-dir=$root" >> $GITHUB_OUTPUT
+
+      - id: unzip-changelog
+        if: ${{ hashFiles('changelog.zip') != '' }}
+        run: unzip changelog.zip
+
       - id: get-deploy-id
         run: |
           deployid=$(<deployid)
-          echo "::set-output name=deploy-id::$deployid"
-
-      - uses: actions/setup-node@v3
+          case "$deployid" in ''|*[!0-9]*) echo "Provided PR number is not an integer"; exit 1 ;; esac
+          echo "deploy-id=$deployid" >> "$GITHUB_OUTPUT"
+
+      - id: get-deploy-url
+        env:
+          ORG: ${{ github.event.repository.owner.login }}
+          REPO: ${{ github.event.repository.name }}
+          DEPLOYID: ${{ steps.get-deploy-id.outputs.deploy-id }}
+        run: |
+          deployurl=$ORG-$REPO-$DEPLOYID.surge.sh
+          echo "deploy-url=$deployurl" >> $GITHUB_OUTPUT
+
+      - uses: actions/setup-node@v4
         with:
           node-version: lts/*
-      
+
       - name: Deploy docs to surge
+        shell: bash
+        env:
+          DEPLOY_URL: ${{ steps.get-deploy-url.outputs.deploy-url }}
+          SURGE_TOKEN: "${{ secrets.DOCS_SURGE_TOKEN }}"
+          SITE_DIR: ${{ steps.get-top-dir.outputs.top-dir }}
         run: |
           npm install -g surge
-          surge ./site ${{ github.event.repository.owner.login}}-${{ github.event.repository.name}}-${{ steps.get-deploy-id.outputs.deploy-id }}.surge.sh --token ${{ secrets.SURGE_TOKEN }}
+          surge ./$SITE_DIR $DEPLOY_URL --token "$SURGE_TOKEN"
 
-      - name: Comment on PR
-        uses: marocchino/sticky-pull-request-comment@v2
+      # If the PR artifacts include a changelog file, add it to the PR as a comment
+      # The changelog contains links to new and changed files in the deployed docs
+      - name: Comment on PR (changelog)
+        if: ${{ hashFiles('changelog') != '' }}
+        uses: marocchino/sticky-pull-request-comment@331f8f5b4215f0445d3c07b4967662a32a2d3e31 #v2.9.0
         with:
           number: ${{ steps.get-deploy-id.outputs.deploy-id }}
+          recreate: true
+          header: docs-pr-changes
+          path: changelog
+          GITHUB_TOKEN: ${{ secrets.DOCS_PR_COMMENT_TOKEN }}
+
+      # If there's no changelog, add a generic comment to the PR
+      - name: Comment on PR (no changelog)
+        if: ${{ hashFiles('changelog') == '' }}
+        env:
+          DEPLOY_URL: ${{ steps.get-deploy-url.outputs.deploy-url }}
+        uses: marocchino/sticky-pull-request-comment@331f8f5b4215f0445d3c07b4967662a32a2d3e31 #v2.9.0
+        with:
+          number: ${{ steps.get-deploy-id.outputs.deploy-id }}
+          header: docs-pr-changes
           message: |
             Looks like you've updated the documentation!
-
-            Check out your changes at https://${{ github.event.repository.owner.login}}-${{ github.event.repository.name}}-${{ steps.get-deploy-id.outputs.deploy-id }}.surge.sh
-          GITHUB_TOKEN: ${{ secrets.PR_COMMENT_TOKEN }}
+            Check out your changes at https://${{ env.DEPLOY_URL }}
+          GITHUB_TOKEN: ${{ secrets.DOCS_PR_COMMENT_TOKEN }}

.github/workflows/docs-pr-checks.yml

@@ -0,0 +1,61 @@
+
+name: "Verify docs PR"
+
+on:
+  pull_request:
+    branches:
+      - "dev"
+      - "5.x"
+      - "4.[0-9]"
+      - "3.5"
+
+jobs:
+
+  #  Generate HTML
+  docs-build-pr:
+    uses: neo4j/docs-tools/.github/workflows/[email protected]
+    with:
+      deploy-id: ${{ github.event.number }}
+      retain-artifacts: 14
+
+  # Parse the json log output from the HTML build, and output warnings and errors as annotations
+  # Optionally, fail the build if there are warnings or errors
+  # By default, the job fails if there are errors, passes if there are warnings only.
+  docs-verify-pr:
+    needs: docs-build-pr
+    uses: neo4j/docs-tools/.github/workflows/[email protected]
+    with:
+      failOnWarnings: true
+
+  # Get lists of changes in the PR
+  # - all updated asciidoc files
+  # - all updated asciidoc pages
+  # - all new asciidoc pages
+  docs-changes-pr:
+    runs-on: ubuntu-latest
+    outputs:
+      asciidoc-files: ${{ steps.get-file-changes.outputs.asciidoc_all_changed_files }}
+      pages-modified: ${{ steps.get-file-changes.outputs.pages_modified_files }}
+      pages-added: ${{ steps.get-file-changes.outputs.pages_added_files }}
+    steps:
+      - name: Get file changes
+        id: get-file-changes
+        uses: tj-actions/changed-files@cbda684547adc8c052d50711417fa61b428a9f88 # v41.1.2
+        with:
+          separator: ','
+          files_yaml: |
+            pages:
+            - modules/**/pages/**/*.adoc
+            asciidoc:
+            - modules/**/*.adoc
+
+  # Generate a PR comment if the docs are using the pageList extension
+  # The extension maps asciidoc source files to their HTML output paths
+  # The comment will contain links to new and changed pages in the deployed HTML docs
+  docs-updates-comment-pr:
+    if: needs.docs-build-pr.outputs.pages-listed == 'success'
+    needs: [docs-build-pr, docs-changes-pr]
+    uses: neo4j/docs-tools/.github/workflows/[email protected]
+    with:
+      pages-modified: ${{ needs.docs-changes-pr.outputs.pages-modified }}
+      pages-added: ${{ needs.docs-changes-pr.outputs.pages-added }}

.github/workflows/docs-teardown.yml

@@ -3,11 +3,6 @@ name: "Documentation Teardown"
 
 on:
   pull_request_target:
-    branches:
-      - "4.4"
-      - "5.0"
-      - "5.x"
-      - "dev"
     types:
       - closed
 
@@ -16,11 +11,35 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v4
         with:
           node-version: lts/*
+
+      - id: get-deploy-url
+        env:
+          ORG: ${{ github.event.repository.owner.login }}
+          REPO: ${{ github.event.repository.name }}
+          DEPLOYID: ${{ github.event.pull_request.number }}
+        run: |
+          deployurl=$ORG-$REPO-$DEPLOYID.surge.sh
+          echo "deploy-url=$deployurl" >> $GITHUB_OUTPUT
       - name: Teardown documentation
+        shell: bash
+        env:
+          SURGE_TOKEN: "${{ secrets.DOCS_SURGE_TOKEN }}"
+          DEPLOY_URL: ${{ steps.get-deploy-url.outputs.deploy-url }}
         run: |
           npm install -g surge
-          surge teardown ${{ github.event.repository.owner.login}}-${{ github.event.repository.name}}-${{ github.event.pull_request.number }}.surge.sh --token ${{ secrets.SURGE_TOKEN }}
-
+          surge teardown $DEPLOY_URL --token "$SURGE_TOKEN"
+
+      - name: Comment on PR
+        uses: marocchino/sticky-pull-request-comment@331f8f5b4215f0445d3c07b4967662a32a2d3e31 #v2.9.0
+        with:
+          number: ${{ github.event.pull_request.number }}
+          header: docs-pr-changes
+          message: |
+            Thanks for the documentation updates.
+
+            The preview documentation has now been torn down - reopening this PR will republish it.
+          GITHUB_TOKEN: ${{ secrets.DOCS_PR_COMMENT_TOKEN }}
+

.gitignore

@@ -32,7 +32,12 @@ shared/
 src/main/_common-and-old/
 tags
 target/
+.vscode/
 
-# node modules
+# docs project
+.env
 node_modules/
-.env
+package-lock.json
+
+# use worktrees for clones of content from other branches so Antora can access it
+worktrees/