From b2d960f6a655df399ad655d2a63a4d83d37dbade Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 27 Sep 2026 13:44:31 -0500 Subject: [PATCH] Docs(ci[deploy]): Publish each release's docs from source why: libtmux.org served one tree for this port, latest, rendered from the API model libtmux/docs had last committed rather than from this repository's source, and no release could be read on its own. what: - Publish latest from master, and each v* tag as its own version plus an alias: next for a prerelease, stable (the default) for a release - Accept workflow_dispatch inputs (source-ref, version, version-kind, is-default, resolves-to, publish), so any ref can be published on demand - Build through libtmux/docs's port-docs.yml, which regenerates the reference from the selected commit, and publish through its reusable-deploy.yml, both pinned to one commit - Build pull requests at their merge commit without publishing, and queue only the publish job, so a pull request never delays a deploy --- .github/workflows/docs.yml | 141 +++++++++++++++++++------------------ 1 file changed, 71 insertions(+), 70 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c2b15938..4a492880 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,94 +1,95 @@ name: docs -# Publishes this port's prose tree to libtmux.org under its own prefix. +# Publishes this port's documentation to libtmux.org: trunk as +# /en/java/latest/, and each `v*` release tag as its own version plus an +# alias, `next` for a prerelease and `stable` (the default) for a release. # -# The tree is built by libtmux/docs's assembly, not by anything in this repo: -# scripts/build-site.sh renders the shared prose with this port's code fences, -# reading THIS checkout for the examples those pages quote. That is why the job -# checks out both repositories and points LIBTMUX_DOCS_CHECKOUT_JAVA at this -# one — without it the build resolves a developer's home directory, finds -# nothing, and fails every inlined example. -# -# Publishes trunk from master to /java/latest. is-default stays -# false, so the tree is reachable and stays out of the search index. +# libtmux/docs builds and publishes the tree, through two reusable workflows +# pinned to one commit: port-docs.yml decides which versions an event builds +# and builds each from this repository's source, and reusable-deploy.yml +# publishes them. Bump both pins together. + on: + pull_request: push: branches: [master] + tags: ['v*'] workflow_dispatch: - -# Workflow level, so a second push queues behind the first rather than racing -# it into the same prefix. -concurrency: - group: docs-deploy-${{ github.repository }} - queue: max + inputs: + source-ref: + description: Exact source ref to build + required: true + default: master + version: + description: URL version slug + required: true + default: latest + version-kind: + description: Version policy + required: true + type: choice + options: [trunk, tag, alias] + default: trunk + is-default: + description: Make this version canonical + required: true + type: boolean + default: false + resolves-to: + description: Immutable target for an alias + required: false + default: '' + publish: + description: Publish after the exact build passes + required: true + type: boolean + default: false permissions: contents: read jobs: + # A pull request builds `latest` without publishing; this port has no + # preview role. build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - with: - path: port - - # A full-length SHA, not a tag. This repository runs that repository's - # build script, and a tag can be repointed — the release name is the - # trailing comment. Bump this and the `uses:` below together: they must - # name the same commit, or the build script and the publish contract - # drift apart. - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - with: - repository: libtmux/docs - ref: 1e459615e9b2bd072b78df46622b1988fe8f88a0 - path: docs - - # The pnpm pin lives in the docs checkout's package.json, not this repo's. - - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6 - with: - package_json_file: docs/package.json - - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7 - with: - node-version: '26' - cache: pnpm - cache-dependency-path: docs/pnpm-lock.yaml - - run: pnpm install --frozen-lockfile - working-directory: docs - - - name: Build this port's tree - working-directory: docs - env: - LIBTMUX_DOCS_CHECKOUT_JAVA: ${{ github.workspace }}/port - run: ./scripts/build-site.sh --ports java --skip-pagefind - - # The directory itself, not its parent: its contents become the contents - # of /java/latest. Uploading docs/_site/en/java would nest the - # tree one level deeper than the prefix already implies. - - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: docs-dist - path: docs/_site/en/java/latest - retention-days: 1 + uses: libtmux/docs/.github/workflows/port-docs.yml@e77d468ebd469155cf2449b962aa9fcea5ad7733 + with: + port: java + source-ref: ${{ inputs.source-ref }} + version: ${{ inputs.version }} + version-kind: ${{ inputs.version-kind }} + is-default: ${{ inputs.is-default == true }} + resolves-to: ${{ inputs.resolves-to }} + publish: ${{ inputs.publish == true }} + # One publication to this port's prefixes at a time, a tag's two legs + # included: both rewrite manifest/java.json. Only publishing queues; a pull + # request's build never waits behind a deploy. `max`, so a queued tag is + # never dropped for a newer run. publish: needs: build + if: needs.build.outputs.should-publish == 'true' + concurrency: + group: docs-deploy-${{ github.repository }} + queue: max + strategy: + fail-fast: false + matrix: ${{ fromJSON(needs.build.outputs.matrix) }} permissions: contents: read id-token: write - uses: libtmux/docs/.github/workflows/reusable-deploy.yml@1e459615e9b2bd072b78df46622b1988fe8f88a0 + uses: libtmux/docs/.github/workflows/reusable-deploy.yml@e77d468ebd469155cf2449b962aa9fcea5ad7733 with: - # Unprefixed by locale — reusable-deploy prepends / itself when - # `port` is set, so this becomes en/java/latest. - path-prefix: java/latest - artifact: docs-dist - version-kind: trunk + # Unprefixed by locale: reusable-deploy prepends / itself when + # `port` is set, so this becomes en/java/. + path-prefix: java/${{ matrix.version }} + artifact: docs-java-${{ matrix.version }} + version-kind: ${{ matrix.kind }} port: java - version: latest - # False while proving the shape: it publishes and stays reachable, but - # robotsFor() keeps it noindex and defaultVersion stays unset, so the - # bare port root still falls through to the landing page. - is-default: false + version: ${{ matrix.version }} + label: ${{ matrix.version }} + is-default: ${{ matrix.isDefault }} + resolves-to: ${{ matrix.resolvesTo }} environment: docs secrets: role-arn: ${{ secrets.LIBTMUX_DOCS_ROLE_ARN }}