diff --git a/.github/workflows/docs-generate-html.yml b/.github/workflows/docs-generate-html.yml index 546fc2e..dbe07aa 100644 --- a/.github/workflows/docs-generate-html.yml +++ b/.github/workflows/docs-generate-html.yml @@ -1,59 +1,69 @@ - name: "Generate HTML" +run-name: "Generate ${{ inputs.publish-env != '' && inputs.publish-env || (github.ref_name == vars.DOCS_PROD_BRANCH && 'prod' || 'dev') }} HTML from ${{ github.ref_name }}" + +permissions: + contents: read -# edit the list of branches according to your repository -# the list of branches should contain all the branches in your Antora publish playbooks +# Builds, verifies, and publishes docs for ONE environment, as a run entirely independent +# of any other environment's run. Triggered (via the API, not a workflow_call) by +# docs-trigger-builds.yml, once per environment that applies to a given push (dev, prod, or both) - +# so if dev's run fails, prod's run is completely unaffected, and vice versa. +# +# No build-ref input: the git ref to build from is always whatever ref this run was +# itself dispatched against (the "Use workflow from" branch when triggered manually, or +# docs-trigger-builds.yml's own `ref:` when triggered automatically - which it always sets +# to the same value it also used to pass as a build-ref input here, so that separate input +# never actually carried any information github.ref_name didn't already have). Reading +# github.ref_name directly instead removes a second, redundant "which branch" box from +# manual dispatch. on: - push: - branches: - - "main" - - "dev" - - "5.x" - - "4.4" workflow_dispatch: - -# change `dev` and `main` according to your repository's branch names -# `dev` is the branch you use to build and publish to staging -# `main` is the branch you use to build and publish to neo4j.com/docs -# in some cases, PROD_BRANCH and DEV_BRANCH may be the same branch -env: - DEV_BRANCH: 'dev' - PROD_BRANCH: 'main' + inputs: + publish-env: + description: "The environment to publish to. Provide a value when the same branch publishes to both 'dev' and 'prod' environments. Otherwise, leave blank." + type: choice + required: false + default: '' + options: + - '' + - 'dev' + - 'prod' jobs: - prepare-ref-env: - name: Set build branch and environments + # Resolves publish-env (dev/prod) once, so neither docs-build nor publish-html + # duplicates the override-or-derive logic. + resolve-env: + name: Resolve environment runs-on: ubuntu-latest outputs: - build-ref: ${{ steps.set-ref-env.outputs.build-ref }} - environments: ${{ steps.set-ref-env.outputs.environments }} + publish-env: ${{ steps.resolve.outputs.publish-env }} steps: - - name: Set Build Ref - id: set-ref-env + - name: Resolve publish-env + id: resolve + env: + PUBLISH_ENV_OVERRIDE: ${{ inputs.publish-env }} + PROD_BRANCH: ${{ vars.DOCS_PROD_BRANCH }} run: | - if [[ "${GITHUB_REF}" == "refs/heads/${{ env.DEV_BRANCH }}" ]]; then - build_from=${{ env.DEV_BRANCH }} - environments='["dev"]' + if [[ -n "${PUBLISH_ENV_OVERRIDE}" ]]; then + publish_env="${PUBLISH_ENV_OVERRIDE}" + elif [[ "${GITHUB_REF_NAME}" == "${PROD_BRANCH}" ]]; then + publish_env="prod" else - build_from=${{ env.PROD_BRANCH }} - environments='["prod"]' + publish_env="dev" fi - # if dev branch = prod branch publish to both - if [[ "${{ env.DEV_BRANCH }}" == "${{ env.PROD_BRANCH }}" ]]; then - environments='["dev","prod"]' - fi - echo "build-ref=${build_from}" >> $GITHUB_OUTPUT - echo "environments=${environments[@]}" >> $GITHUB_OUTPUT + + echo "publish-env=${publish_env}" >> $GITHUB_OUTPUT docs-build: name: Generate HTML - needs: prepare-ref-env + needs: resolve-env uses: neo4j/docs-tools/.github/workflows/reusable-docs-build.yml@v2 with: package-script: 'verify:publish' - build-ref: ${{needs.prepare-ref-env.outputs.build-ref}} + build-ref: ${{ github.ref_name }} fetch-depth: 0 + publish-env: ${{ needs.resolve-env.outputs.publish-env }} docs-verify: name: Verify HTML @@ -64,15 +74,10 @@ jobs: publish-html: name: Publish HTML - needs: [docs-verify, prepare-ref-env] + needs: [docs-verify, resolve-env] runs-on: ubuntu-latest - - strategy: - matrix: - environments: ${{ fromJson(needs.prepare-ref-env.outputs.environments) }} - steps: - - name: Publish to ${{ matrix.environments }} + - name: Publish to ${{ needs.resolve-env.outputs.publish-env }} uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 #v4 with: token: ${{ secrets.DOCS_DISPATCH_TOKEN }} @@ -83,10 +88,5 @@ jobs: "org": "${{ github.repository_owner }}", "repo": "${{ github.event.repository.name }}", "run_id": "${{ github.run_id }}", - "publish_env": "${{ matrix.environments }}" + "publish_env": "${{ needs.resolve-env.outputs.publish-env }}" } - - - name: Echo - if: ${{ matrix.environments == 'prod' }} - run: | - echo "If this step runs then approval has been granted" >> $GITHUB_STEP_SUMMARY diff --git a/.github/workflows/docs-generate-pdf.yml b/.github/workflows/docs-generate-pdf.yml new file mode 100644 index 0000000..eaa3123 --- /dev/null +++ b/.github/workflows/docs-generate-pdf.yml @@ -0,0 +1,88 @@ +name: "Generate PDF" +run-name: "Generate ${{ inputs.publish-env != '' && inputs.publish-env || (github.ref_name == vars.DOCS_PROD_BRANCH && 'prod' || 'dev') }} PDF from ${{ github.ref_name }}" + +permissions: + contents: read + +# Mirrors docs-generate-html.yml's shape (workflow_dispatch with a publish-env input, +# resolve-env -> build -> publish) and its own reusable-workflow reference convention (a +# pinned neo4j/docs-tools/...@v2 tag, not a relative path - this repo doesn't contain +# reusable-docs-pdf-build.yml itself). Still simpler than docs-generate-html.yml in one +# way: there's no docs-verify step (no equivalent check exists yet for a PDF), and +# build/publish are two plain jobs rather than a reusable-workflow call plus a verify call. +# +# No build-ref input - see docs-generate-html.yml's own comment on why: the git ref to +# build from is always whatever ref this run was itself dispatched against. +on: + workflow_dispatch: + inputs: + publish-env: + description: "The environment to publish to. Provide a value when the same branch publishes to both 'dev' and 'prod' environments. Otherwise, leave blank." + type: choice + required: false + default: '' + options: + - '' + - 'dev' + - 'prod' + +jobs: + + # Resolves publish-env (dev/prod) once, so publish-pdf doesn't duplicate the + # override-or-derive logic - same job as docs-generate-html.yml's own resolve-env. + resolve-env: + name: Resolve environment + runs-on: ubuntu-latest + outputs: + publish-env: ${{ steps.resolve.outputs.publish-env }} + steps: + - name: Resolve publish-env + id: resolve + env: + PUBLISH_ENV_OVERRIDE: ${{ inputs.publish-env }} + PROD_BRANCH: ${{ vars.DOCS_PROD_BRANCH }} + run: | + if [[ -n "${PUBLISH_ENV_OVERRIDE}" ]]; then + publish_env="${PUBLISH_ENV_OVERRIDE}" + elif [[ "${GITHUB_REF_NAME}" == "${PROD_BRANCH}" ]]; then + publish_env="prod" + else + publish_env="dev" + fi + + echo "publish-env=${publish_env}" >> $GITHUB_OUTPUT + + docs-build-pdf: + name: Generate PDF + needs: resolve-env + uses: neo4j/docs-tools/.github/workflows/reusable-docs-pdf-build.yml@v2 + with: + build-ref: ${{ github.ref_name }} + fetch-depth: 0 + publish-env: ${{ needs.resolve-env.outputs.publish-env }} + + # Hand off to docs-publish (a separate repo) to actually publish this run's "pdf" + # artifact - same mechanism docs-generate-html.yml already uses for its "docs" + # artifact. docset/version come from docs-build-pdf itself (read back out of the + # PDF's own build path - see reusable-docs-pdf-build.yml), since there's no HTML + # directory tree here for docs-publish to infer them from the way it does for HTML. + publish-pdf: + name: Publish PDF + needs: [docs-build-pdf, resolve-env] + runs-on: ubuntu-latest + steps: + - name: Publish to ${{ needs.resolve-env.outputs.publish-env }} + uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 #v4 + with: + token: ${{ secrets.DOCS_DISPATCH_TOKEN }} + repository: neo4j/docs-publish + event-type: publish-pdf + client-payload: |- + { + "org": "${{ github.repository_owner }}", + "repo": "${{ github.event.repository.name }}", + "run_id": "${{ github.run_id }}", + "publish_env": "${{ needs.resolve-env.outputs.publish-env }}", + "docset": "${{ needs.docs-build-pdf.outputs.docset }}", + "version": "${{ needs.docs-build-pdf.outputs.version }}" + } diff --git a/.github/workflows/docs-trigger-builds.yml b/.github/workflows/docs-trigger-builds.yml new file mode 100644 index 0000000..883a27a --- /dev/null +++ b/.github/workflows/docs-trigger-builds.yml @@ -0,0 +1,172 @@ +name: "Trigger docs builds" + +# This workflow's job is dispatching docs-generate-html.yml and docs-generate-pdf.yml +# with the right build-ref(s) for whatever just happened - it is NOT the only valid way +# to wire this up. It doesn't publish anything itself - the dispatched workflows hand +# off to the (separate) docs-publish repo for that. +# +# Use this (docs-trigger-builds.yml -> docs-generate-*.yml) when a single trigger might +# legitimately need to build more than one environment - e.g. a repo where +# DOCS_DEV_BRANCH == DOCS_PROD_BRANCH (one branch serving both, so every push to it +# always means both). +# +# If your repo instead has clean, separate dev/prod branches, you may not need this at +# all: docs-generate-html.yml can be given its own direct `on: push: branches: [...]` +# trigger per environment instead - simpler, and structurally can't build the wrong +# branch's content into the wrong environment. This template still works fine for that +# shape too (it will just always resolve to a single build), so which to use is a +# judgment call, not a hard requirement. + +permissions: + contents: read + actions: write + +# edit the list of branches according to your repository - every branch that should +# trigger a rebuild, including older versioned content branches (a push there still +# needs to refresh dev/prod's current HTML and this push's own PDF). +on: + push: + branches: + - 'dev' + - 'main' + - '5.x' + - '4.4' + workflow_dispatch: + +jobs: + + prepare-builds: + name: Set builds to trigger + runs-on: ubuntu-latest + outputs: + # JSON array of {workflow, buildRef, publishEnv} - one entry per independent + # dispatch to make. publishEnv is left '' for docs-generate-html.yml except in + # the one case where it's genuinely ambiguous (see below) - that workflow + # derives it itself from build-ref against its own vars.DOCS_PROD_BRANCH + # whenever publishEnv is blank. docs-generate-pdf.yml's publishEnv is always + # resolved explicitly here instead, using the same conservative default as the + # HTML rules below: the dev branch is the only case treated as dev, every other + # branch defaults to prod. + builds: ${{ steps.set-builds.outputs.builds }} + steps: + # DOCS_DEV_BRANCH and DOCS_PROD_BRANCH are required repository variables + # (Settings -> Secrets and variables -> Actions -> Variables), not values to edit + # here. docs-generate-html.yml, docs-generate-pdf.yml, and docs-publish (a + # separate repo) all independently read the same variables, so they can't be set + # by editing this file on a branch/PR. + # `dev` is the branch you use to build and publish to staging. + # `main` is the branch you use to build and publish to neo4j.com/docs. + # If your repo has no separate prod environment, set DOCS_PROD_BRANCH equal to + # DOCS_DEV_BRANCH - every push will then resolve to both (see the rules below). + - name: Set builds + id: set-builds + env: + DEV_BRANCH: ${{ vars.DOCS_DEV_BRANCH }} + PROD_BRANCH: ${{ vars.DOCS_PROD_BRANCH }} + run: | + dev_branch="${DEV_BRANCH}" + prod_branch="${PROD_BRANCH}" + + if [[ -z "${dev_branch}" ]]; then + echo "::error::vars.DOCS_DEV_BRANCH is not set for this repository. Set it in Settings -> Secrets and variables -> Actions -> Variables." + exit 1 + fi + if [[ -z "${prod_branch}" ]]; then + echo "::error::vars.DOCS_PROD_BRANCH is not set for this repository. Set it in Settings -> Secrets and variables -> Actions -> Variables." + exit 1 + fi + + # HTML rules: + # - DEV_BRANCH == PROD_BRANCH -> both, always (one branch serves both, so + # there's no "the other one didn't change" case to worry about). + # - The triggering branch IS the dev branch -> dev only (a change on dev has + # no bearing on prod's already-published content). + # - Anything else (including a push to the prod branch, or any other branch) + # -> both. We deliberately don't try to be clever about only rebuilding the + # one that "actually changed" - e.g. a branch that's fallen out of the dev + # set but is still in the prod set would be misdetected either way, so we + # just always rebuild everything except the one case (dev branch) we know + # for certain doesn't affect prod. + if [[ "${dev_branch}" == "${prod_branch}" ]]; then + html_builds=$(jq -nc --arg b "$dev_branch" \ + '[{workflow:"docs-generate-html.yml",buildRef:$b,publishEnv:"dev"},{workflow:"docs-generate-html.yml",buildRef:$b,publishEnv:"prod"}]') + elif [[ "${GITHUB_REF}" == "refs/heads/${dev_branch}" ]]; then + html_builds=$(jq -nc --arg dev "$dev_branch" \ + '[{workflow:"docs-generate-html.yml",buildRef:$dev,publishEnv:""}]') + else + html_builds=$(jq -nc --arg dev "$dev_branch" --arg prod "$prod_branch" \ + '[{workflow:"docs-generate-html.yml",buildRef:$dev,publishEnv:""},{workflow:"docs-generate-html.yml",buildRef:$prod,publishEnv:""}]') + fi + + # PDF always builds from the branch that triggered this run - no dev/prod + # pairing to work out the way HTML has to (there's only ever one PDF build + # per trigger). Its publish-env is still dev or prod, though, resolved with + # the same conservative default the HTML rules above use: the dev branch is + # the one case known for certain not to affect prod, so it's the only one + # that resolves to dev - every other branch (the real prod branch, a third + # long-lived branch, a typo, ...) resolves to prod. + if [[ "${GITHUB_REF}" == "refs/heads/${dev_branch}" ]]; then + pdf_publish_env="dev" + else + pdf_publish_env="prod" + fi + pdf_build=$(jq -nc --arg ref "${GITHUB_REF_NAME}" --arg env "$pdf_publish_env" \ + '[{workflow:"docs-generate-pdf.yml",buildRef:$ref,publishEnv:$env}]') + + builds=$(jq -nc --argjson html "$html_builds" --argjson pdf "$pdf_build" '$html + $pdf') + echo "builds=${builds}" >> $GITHUB_OUTPUT + + # One matrix job instance per build prepare-builds resolved, each dispatching its + # target workflow as its own separate run - not a workflow_call (which would keep + # them all in this one run), so each is fully independent: fail-fast: false means + # one matrix instance failing to dispatch doesn't cancel the others, and each + # dispatched run ends up with its own normally-named artifacts (no collisions, since + # they're separate runs, not jobs sharing one run). + trigger-builds: + name: Trigger ${{ matrix.build.workflow }} (${{ matrix.build.buildRef }}) + needs: prepare-builds + strategy: + fail-fast: false + matrix: + build: ${{ fromJson(needs.prepare-builds.outputs.builds) }} + runs-on: ubuntu-latest + steps: + - name: Dispatch + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 + env: + BUILD: ${{ toJson(matrix.build) }} + PROD_BRANCH: ${{ vars.DOCS_PROD_BRANCH }} + with: + script: | + const build = JSON.parse(process.env.BUILD) + const prodBranch = process.env.PROD_BRANCH + // Both docs-generate-html.yml and docs-generate-pdf.yml accept publish-env. + // Neither has a build-ref input - the ref: below is what determines the git + // ref the dispatched run actually builds from (github.ref_name inside it), + // so a separate build-ref input would only ever duplicate this same value. + const inputs = { 'publish-env': build.publishEnv } + await github.rest.actions.createWorkflowDispatch({ + owner: context.repo.owner, + repo: context.repo.repo, + workflow_id: build.workflow, + // Dispatch from build.buildRef itself, NOT the branch that triggered + // this workflow - a dispatched run's ref becomes its real head_branch, + // which is exactly what docs-publish's check-build-branch inspects. + // Using a single fixed ref for every build here would make every + // dispatched run's head_branch equal whatever branch triggered THIS + // workflow, regardless of which environment it's actually building for + // - so a trigger from any branch other than build.buildRef (e.g. a + // versioned content branch, or the "other" HTML build when both are + // triggered) would always fail that check downstream, even for an + // otherwise-legitimate build. + ref: build.buildRef, + inputs, + }) + // Mirrors docs-generate-html.yml's own publish-env derivation for + // display purposes only - the real derivation happens inside the + // dispatched run, this is just to show what it will resolve to when no + // explicit override was passed (the empty-string case, only possible for + // an HTML build - see prepare-builds above). + const env = build.publishEnv || (build.buildRef === prodBranch ? 'prod' : 'dev') + core.summary.addRaw(`Triggered \`${build.workflow}\` on branch \`${build.buildRef}\` for \`${env}\``, true) + await core.summary.write() diff --git a/antora.yml b/antora.yml index 5108dc1..c994a64 100644 --- a/antora.yml +++ b/antora.yml @@ -1,14 +1,14 @@ name: java-reference title: Java Reference -version: '2026.09' +version: '2026.10' start_page: ROOT:index.adoc nav: - modules/ROOT/content-nav.adoc asciidoc: attributes: - neo4j-version: '2026.09' - neo4j-version-exact: '2026.09.0' - neo4j-buildnumber: '2026.09' + neo4j-version: '2026.10' + neo4j-version-exact: '2026.10.0' + neo4j-buildnumber: '2026.10' java-driver-version: '6.2.1' neo4j-documentation-branch: 'dev' page-origin-private: false