diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml new file mode 100644 index 000000000..05bb16ce9 --- /dev/null +++ b/.github/workflows/ci.yaml @@ -0,0 +1,64 @@ +name: ci + +on: + pull_request: + branches: + - main + - 'release-*' + types: + - opened + - reopened + - synchronize + - closed + +permissions: + contents: read # Baseline for actions/checkout; elevated scopes are granted per-job + +concurrency: + group: pages-preview-${{ github.event.pull_request.number }} + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + permissions: + contents: read # Only reads for checkout; gh-pages push and PR comment use the platform-mesh-publisher app token + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + fetch-depth: 0 + persist-credentials: false + + - id: app-token + name: Generate platform-mesh-publisher app token + if: ${{ !github.event.pull_request.head.repo.fork }} # Secrets are unavailable on fork PRs; preview deploy below is likewise skipped + uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0 + with: + app-id: "1415820" # platform-mesh-publisher + private-key: ${{ secrets.PM_PUBLISHER_PRIVATE_KEY }} + permission-contents: write + permission-pull-requests: write + + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7 + with: + node-version: 24 + cache: npm + + - id: configure + uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6 + + - id: set-version + name: Set documentation version + run: echo "version=" >> $GITHUB_OUTPUT + + - run: npm ci + - run: npm run build + env: + DOCS_VERSION: ${{ steps.set-version.outputs.version }} + PAGES_BASE: ${{ format('pr-preview/pr-{0}', github.event.pull_request.number) }} + + - uses: rossjrw/pr-preview-action@ffa7509e91a3ec8dfc2e5536c4d5c1acdf7a6de9 # v1 + if: ${{ !github.event.pull_request.head.repo.fork }} + with: + token: ${{ steps.app-token.outputs.token }} + source-dir: .vitepress/dist diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml deleted file mode 100644 index 4025493f2..000000000 --- a/.github/workflows/pages.yaml +++ /dev/null @@ -1,96 +0,0 @@ -name: pages - -on: - push: - branches: - - main - - 'release-*' # Support version branches - pull_request: - branches: - - main - - 'release-*' - types: - - opened - - reopened - - synchronize - - closed - workflow_dispatch: - -permissions: - contents: read # Only reads for checkout; gh-pages push and PR comment use the platform-mesh-publisher app token - -concurrency: - # set separate concurrency groups for each version branch and PR - group: ${{ github.event_name == 'pull_request' && format('pages-preview-{0}', github.event.pull_request.number) || format('pages-{0}', github.ref_name) }} - cancel-in-progress: false - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6 - with: - fetch-depth: 0 - persist-credentials: false - - - id: app-token - name: Generate platform-mesh-publisher app token - if: ${{ !github.event.pull_request.head.repo.fork }} # Secrets are unavailable on fork PRs; preview deploy below is likewise skipped - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0 - with: - app-id: "1415820" # platform-mesh-publisher - private-key: ${{ secrets.PM_PUBLISHER_PRIVATE_KEY }} - permission-contents: write - permission-pull-requests: write - - - uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6 - with: - node-version: 24 - cache: npm - - - id: configure - uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5 - - # Extract version from branch name for versioned deployments - - id: set-version - name: Set documentation version - run: | - if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then - echo "version=main" >> $GITHUB_OUTPUT - elif [[ "${{ github.ref }}" == refs/heads/release-* ]]; then - echo "version=${GITHUB_REF#refs/heads/}" >> $GITHUB_OUTPUT - else - echo "version=" >> $GITHUB_OUTPUT - fi - - - run: npm ci - - run: npm run build - env: - DOCS_VERSION: ${{ steps.set-version.outputs.version }} - PAGES_BASE: ${{ github.event_name == 'pull_request' && format('pr-preview/pr-{0}', github.event.pull_request.number) || '' }} - - # deploy the PR to a preview URL - - uses: rossjrw/pr-preview-action@8ff09e486b4c23709012eedd3b42e9f0b95dd0c5 # v1 - if: ${{ github.event_name == 'pull_request' && !github.event.pull_request.head.repo.fork }} - with: - token: ${{ steps.app-token.outputs.token }} - source-dir: .vitepress/dist - - # Deploy versioned docs to GitHub Pages - # This creates a folder structure on gh-pages branch for each version: - # gh-pages/ - # ├── main/ ← from main branch - # ├── release-0.1/ ← from release-0.1 branch - # └── pr-preview/ ← PR previews (preserved via clean-exclude) - # - # Each version is independent - deploying main/ won't affect release-0.1/ - # The target-folder determines which subdirectory receives the build output - - uses: JamesIves/github-pages-deploy-action@4a3abc783e1a24aeb44c16e869ad83caf6b4cc23 # v4 - if: ${{ (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release-')) }} - with: - token: ${{ steps.app-token.outputs.token }} - folder: .vitepress/dist - branch: gh-pages - target-folder: ${{ steps.set-version.outputs.version }} - clean-exclude: pr-preview - force: false diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 000000000..5263ea21c --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,86 @@ +name: release + +on: + push: + branches: + - main + - 'release-*' + workflow_dispatch: + +permissions: + contents: read # Baseline for actions/checkout; elevated scopes are granted per-job + +concurrency: + group: pages-${{ github.ref_name }} + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + permissions: + contents: read # Only reads for checkout; pushes to gh-pages use the platform-mesh-publisher app token + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + fetch-depth: 0 + persist-credentials: false + + - id: app-token + name: Generate platform-mesh-publisher app token + uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0 + with: + app-id: "1415820" # platform-mesh-publisher + private-key: ${{ secrets.PM_PUBLISHER_PRIVATE_KEY }} + permission-contents: write + + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7 + with: + node-version: 24 + cache: npm # zizmor: ignore[cache-poisoning] + + - id: configure + uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6 + + - id: set-version + name: Set documentation version + run: | + if [[ "${GITHUB_REF}" == "refs/heads/main" ]]; then + echo "version=main" >> $GITHUB_OUTPUT + elif [[ "${GITHUB_REF}" == refs/heads/release-* ]]; then + echo "version=${GITHUB_REF#refs/heads/}" >> $GITHUB_OUTPUT + else + echo "version=" >> $GITHUB_OUTPUT + fi + + - run: npm ci + - run: npm run build + env: + DOCS_VERSION: ${{ steps.set-version.outputs.version }} + PAGES_BASE: '' + + - uses: JamesIves/github-pages-deploy-action@fa24774553152dd7873cd16ebd8d959b010c5445 # v4 + if: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release-') }} + with: + token: ${{ steps.app-token.outputs.token }} + folder: .vitepress/dist + branch: gh-pages + target-folder: ${{ steps.set-version.outputs.version }} + clean-exclude: pr-preview + force: false + + - uses: JamesIves/github-pages-deploy-action@fa24774553152dd7873cd16ebd8d959b010c5445 # v4 + if: ${{ github.ref == 'refs/heads/main' }} + with: + token: ${{ steps.app-token.outputs.token }} + folder: . + branch: gh-pages + target-folder: . + clean: false + clean-exclude: | + pr-preview + main + release-* + force: false + include: | + index.html + llms.txt diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 0c54ff301..0e2b6cf55 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -25,7 +25,10 @@ const base = 'DOCS_VERSION' in process.env && process.env.DOCS_VERSION != '' export default withMermaid({ title: "Platform Mesh", head: [ - ['link', { rel: 'icon', href: `${base}favicon.ico` }] + ['link', { rel: 'icon', href: `${base}favicon.ico` }], + // Deliberately synchronous: the shared version list must be available before + // Vue mounts. Use the site root, not this build's release/preview base path. + ['script', { src: '/versions.js' }] ], base, diff --git a/.vitepress/theme/components/VersionSelector.vue b/.vitepress/theme/components/VersionSelector.vue index b82607959..ff95b3869 100644 --- a/.vitepress/theme/components/VersionSelector.vue +++ b/.vitepress/theme/components/VersionSelector.vue @@ -33,20 +33,15 @@ interface Version { rootOnly?: boolean } -// Define available versions - update this list when adding new versions. -// Set rootOnly: true for versions whose URL structure differs from the current -// docs layout (pre-v0.3 used a different directory structure), so switching -// to them always lands on the version root instead of trying to map the -// current path. -const versions: Version[] = [ - { name: 'main', label: 'main (latest)' }, - { name: 'release-26.10', label: 'v26.10' }, - { name: 'release-0.5', label: 'v0.5' }, - { name: 'release-0.4', label: 'v0.4' }, - { name: 'release-0.3', label: 'v0.3' }, - { name: 'release-0.2', label: 'v0.2', rootOnly: true }, - { name: 'release-0.1', label: 'v0.1', rootOnly: true }, -] +declare global { + interface Window { + PLATFORM_MESH_VERSIONS?: Version[] + } +} + +// The root-level /versions.js is shared by all documentation releases. +// Keep server rendering independent of window; load the list on mount. +const versions = ref([{ name: 'main', label: 'main (latest)' }]) const currentVersion = ref('') const isPreview = ref(false) @@ -67,12 +62,10 @@ function getCurrentVersion(): string { const path = window.location.pathname const segments = path.split('/').filter(Boolean) - // Check if first segment matches a known version - if (segments.length > 0) { - const firstSegment = segments[0] - if (versions.some(v => v.name === firstSegment)) { - return firstSegment - } + // Detect the current release even when the shared script is unavailable. + const firstSegment = segments[0] + if (firstSegment === 'main' || /^release-\d+\.\d+$/.test(firstSegment || '')) { + return firstSegment } // Default to main if no version detected @@ -82,7 +75,7 @@ function getCurrentVersion(): string { function switchVersion(): void { if (typeof window === 'undefined') return - const selected = versions.find(v => v.name === currentVersion.value) + const selected = versions.value.find(v => v.name === currentVersion.value) if (selected?.rootOnly) { window.location.href = `/${currentVersion.value}/` @@ -94,7 +87,7 @@ function switchVersion(): void { // Remove the version from the path if it exists let pathWithoutVersion = '' - if (segments.length > 0 && versions.some(v => v.name === segments[0])) { + if (segments.length > 0 && versions.value.some(v => v.name === segments[0])) { pathWithoutVersion = '/' + segments.slice(1).join('/') } else { pathWithoutVersion = currentPath @@ -117,6 +110,19 @@ function switchVersion(): void { onMounted(() => { isPreview.value = isPreviewContext() currentVersion.value = getCurrentVersion() + if (window.PLATFORM_MESH_VERSIONS?.length) { + versions.value = [...window.PLATFORM_MESH_VERSIONS] + } + + // Local builds, a failed script request, or a stale cached list should still + // show the current version and allow navigation back to main. + if (!versions.value.some(v => v.name === currentVersion.value)) { + versions.value.push({ + name: currentVersion.value, + label: `v${currentVersion.value.replace(/^release-/, '')}`, + rootOnly: ['release-0.1', 'release-0.2'].includes(currentVersion.value), + }) + } }) diff --git a/hack/generate-versions.mjs b/hack/generate-versions.mjs new file mode 100644 index 000000000..7d8493ad0 --- /dev/null +++ b/hack/generate-versions.mjs @@ -0,0 +1,48 @@ +#!/usr/bin/env node +// Generate the shared script from successfully deployed documentation, not +// branches that might not have a working deployment yet. No npm dependencies. +import { access, mkdir, readdir, writeFile } from 'node:fs/promises' +import { dirname, join, resolve } from 'node:path' +import { pathToFileURL } from 'node:url' + +export async function generateVersions(deploymentDirectory) { + const versions = [] + for (const entry of await readdir(deploymentDirectory, { withFileTypes: true })) { + if (!entry.isDirectory()) continue + if (entry.name !== 'main' && !/^release-\d+\.\d+$/.test(entry.name)) continue + try { + await access(join(deploymentDirectory, entry.name, 'index.html')) + } catch (error) { + if (error.code === 'ENOENT') continue + throw error + } + versions.push({ + name: entry.name, + label: entry.name === 'main' ? 'main (latest)' : `v${entry.name.slice('release-'.length)}`, + ...(['release-0.1', 'release-0.2'].includes(entry.name) ? { rootOnly: true } : {}), + }) + } + return versions.sort((a, b) => { + if (a.name === 'main') return -1 + if (b.name === 'main') return 1 + return b.name.localeCompare(a.name, 'en', { numeric: true }) + }) +} + +export function renderVersions(versions) { + return '// Generated from deployed documentation. Do not edit.\n' + + `window.PLATFORM_MESH_VERSIONS = ${JSON.stringify(versions, null, 2)};\n` +} + +if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) { + const [, , deploymentDirectory, outputFile] = process.argv + if (!deploymentDirectory || !outputFile) { + console.error('Usage: node hack/generate-versions.mjs ') + process.exitCode = 1 + } else { + const versions = await generateVersions(deploymentDirectory) + if (!versions.length) throw new Error('No deployed documentation versions found') + await mkdir(dirname(outputFile), { recursive: true }) + await writeFile(outputFile, renderVersions(versions)) + } +} diff --git a/hack/generate-versions.test.mjs b/hack/generate-versions.test.mjs new file mode 100644 index 000000000..82b9fb50e --- /dev/null +++ b/hack/generate-versions.test.mjs @@ -0,0 +1,42 @@ +import assert from 'node:assert/strict' +import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { test } from 'node:test' +import { runInNewContext } from 'node:vm' +import { generateVersions, renderVersions } from './generate-versions.mjs' + +test('discovers deployed releases, sorts numerically, and preserves legacy navigation', async t => { + const root = await mkdtemp(join(tmpdir(), 'pm-versions-')) + t.after(() => rm(root, { recursive: true, force: true })) + for (const name of [ + 'main', 'release-0.1', 'release-0.2', 'release-0.3', 'release-0.5', + 'release-26.9', 'release-26.10', 'release-27.1', 'pr-preview', + 'release-unpublished', 'release-26.11', + ]) { + await mkdir(join(root, name)) + if (name !== 'release-26.11') await writeFile(join(root, name, 'index.html'), '') + } + await writeFile(join(root, 'release-28.1'), 'not a directory') + + const versions = await generateVersions(root) + assert.deepEqual(versions.map(v => v.name), [ + 'main', 'release-27.1', 'release-26.10', 'release-26.9', + 'release-0.5', 'release-0.3', 'release-0.2', 'release-0.1', + ]) + assert.equal(versions[0].label, 'main (latest)') + assert.equal(versions[2].label, 'v26.10') + assert.deepEqual(versions.filter(v => v.rootOnly).map(v => v.name), [ + 'release-0.2', 'release-0.1', + ]) + + const window = {} + runInNewContext(renderVersions(versions), { window }) + assert.equal(JSON.stringify(window.PLATFORM_MESH_VERSIONS), JSON.stringify(versions)) +}) + +test('an empty deployment contains no versions', async t => { + const root = await mkdtemp(join(tmpdir(), 'pm-versions-')) + t.after(() => rm(root, { recursive: true, force: true })) + assert.deepEqual(await generateVersions(root), []) +}) diff --git a/hack/how-to.md b/hack/how-to.md index da4ae0323..bc3943105 100644 --- a/hack/how-to.md +++ b/hack/how-to.md @@ -163,37 +163,40 @@ git push -u origin release-0.1 ### Updating the Version Selector -After creating a new release branch, add it to the dropdown: +No manual version-list updates are needed. Every successful documentation deployment +runs a serialized `versions` job in `.github/workflows/release.yml`. It checks out +`gh-pages`, discovers deployed `main/` and `release-X.Y/` directories containing an +`index.html`, and publishes a single `/versions.js` at the site root. Releases are +sorted numerically, newest first, with main at the top. A branch without a deployed +site is not advertised. + +Every documentation build includes this shared script synchronously in ``, +before Vue initializes the dropdown. It is intentionally loaded from `/versions.js`, +not from the release's base path. Old releases therefore see newly deployed versions +without being rebuilt. Browser/GitHub Pages caching may briefly delay updates. +If the script is unavailable, the dropdown falls back to main and the current release. +PR previews continue to hide the selector. + +The generator lives in `hack/generate-versions.mjs` and is always loaded from main +by the deployment job. It retains `rootOnly` navigation for releases 0.1 and 0.2. +Run its tests with `npm test`. + +Both publishing jobs use the `github-pages` GitHub environment. In repository +**Settings → Environments → github-pages**, ensure the deployment branch policy +allows `main` and `release-*` before deploying these workflow changes to release +branches. Environment policies apply to the workflow's source branch, even though +it publishes files to `gh-pages`. + +**Local testing:** a single-version VitePress server does not have the root-level +shared script; a 404 for `/versions.js` is expected and exercises the fallback. +To test the full dropdown with the multi-version `test-deploy/` setup above, generate +the shared script before serving that directory: ```bash -# 1. Edit the version selector component -git checkout main -``` - -Edit `.vitepress/theme/components/VersionSelector.vue`: - -```typescript -const versions: Version[] = [ - { name: 'main', label: 'main (latest)' }, - { name: 'release-0.2', label: 'v0.2' }, // Add new versions here - { name: 'release-0.1', label: 'v0.1' }, -] +node hack/generate-versions.mjs test-deploy test-deploy/versions.js ``` -```bash -# 2. Commit and push -git add .vitepress/theme/components/VersionSelector.vue -git commit -m "Add release-0.2 to version selector" -git push origin main -``` - -**Apply to other branches (optional):** -```bash -# Update the dropdown on release branches too -git checkout release-0.1 -git cherry-pick -git push origin release-0.1 -``` +You can use the same command with a local checkout of `gh-pages` as the first argument. ### Updating Release Documentation @@ -514,15 +517,16 @@ git push origin release-0.2 ### Version Selector Management -**Keep it updated:** -- Add new versions to dropdown when created -- List versions in reverse chronological order (newest first, except main) -- Use clear labels (`main (latest)`, `v0.2`, `v0.1`) +The shared `/versions.js` is regenerated automatically after each documentation +deployment. Do not edit the generated file or maintain per-branch version lists. **Remove old versions:** -1. Delete the branch: `git push origin --delete release-0.1` -2. Remove from dropdown in `VersionSelector.vue` -3. Optionally: manually delete from `gh-pages` branch +1. Delete the source branch if it is no longer needed. +2. Delete its deployed directory (for example `release-0.1/`) from `gh-pages`. +3. Run the release workflow on main to regenerate `/versions.js`. + +Deleting only a source branch does not unpublish its documentation or remove it +from the dropdown. The deployed directories are the source of truth. ### Testing Before Merging diff --git a/package.json b/package.json index bb57a846b..f1a00472e 100644 --- a/package.json +++ b/package.json @@ -6,6 +6,7 @@ "scripts": { "dev": "vitepress dev", "build": "vitepress build", - "preview": "vitepress preview" + "preview": "vitepress preview", + "test": "node --test hack/*.test.mjs" } }