Skip to content

docs: automate PRs for new platform version pages - #3

Merged
chrispaterson merged 1 commit into
paterson/GRAPH-3863/port-plugin-developer-guidefrom
paterson/GRAPH-auto-platform-version-pr
Aug 27, 2026
Merged

docs: automate PRs for new platform version pages#3
chrispaterson merged 1 commit into
paterson/GRAPH-3863/port-plugin-developer-guidefrom
paterson/GRAPH-auto-platform-version-pr

Conversation

@chrispaterson

@chrispaterson chrispaterson commented Aug 27, 2026

Copy link
Copy Markdown
Collaborator

Description

Automates publishing of the Platform Library Reference pages so a new platform
version gets a documentation PR without manual work.

  • scripts/sync-platform-versions.py (new) — detects platform versions published to the
    prod archival endpoint (graph.adobe.com/graph/platform/, GRAPH-3604) that have no page
    yet, and downloads each one's @graph/platform-exports bundle. Discovery uses the public,
    unauthenticated major/<n> redirect (latest minor per major) and
    version/<v>/platform-closure.json, walking each major down until it hits an
    already-documented version — so it backfills multiple new minors at once and skips
    historical gaps (e.g. the 2.2 that never shipped). Stdlib only. The version number always
    comes from the endpoint path, never a tarball filename (the exports tarball keeps its
    own package version, e.g. graph-platform-exports-2.11.2.tgz under version/2.17/).
  • scripts/gen-platform-pages.py — gains a --version X.Y single-version mode, and
    write_index() now derives the version list from the pages present on disk rather than
    from BUNDLE_DIR. This lets one new version be rendered with a correct, complete index
    without needing every other version's bundle available.
  • .github/workflows/check-platform-version.yml (new) — daily cron + manual dispatch:
    sync → generate → lint → open a reviewed PR (peter-evans/create-pull-request).

Motivation and Context

Each new platform release ships a fixed set of importable libraries that plugin authors need
documented. Today that page is produced by hand-running gen-platform-pages.py. This closes
the loop: the docs site polls the same archival endpoint the SDK resolves against, and opens
a ready-to-review PR whenever a new version appears — keeping the reference current with no
standing manual step.

How Has This Been Tested?

Verified end-to-end against the live prod endpoint (graph.adobe.com):

  • Reachability — the archival endpoint is a public CloudFront distribution, no auth; the
    version path returns 200 JSON from a non-corp vantage, unknown majors 404, major/<n>
    302-redirects to the latest minor.
  • Idempotency — downloading the real 2.17 bundle and running --version 2.17
    reproduces the committed page and index with an empty git diff.
  • Add path — a simulated 2.18 produces a new page and moves the — latest marker
    correctly in the index.
  • Sync steady state — with everything through 2.17 documented, the sync script prints
    nothing and downloads nothing (workflow no-ops).
  • Sync detection — hiding the 2.17 page makes the sync script detect and download exactly
    2.17 (stops at the first already-documented version below it).
  • Both scripts py_compile clean.

Screenshots (if appropriate):

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

  • I have signed the Adobe Open Source CLA.
  • My code follows the code style of this project.
  • My change requires a change to the documentation.
  • I have updated the documentation accordingly.
  • I have read the CONTRIBUTING document.
  • I have added tests to cover my changes.
  • All new and existing tests passed.

Add a scheduled workflow that documents new platform versions without manual
intervention. sync-platform-versions.py detects versions published to the prod
archival endpoint (GRAPH-3604) that lack a page and downloads their bundles;
gen-platform-pages.py gains a --version mode and builds its index from pages on
disk, so a single new version can be rendered without every other bundle present.
The workflow generates, lints, and opens a reviewed PR.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@chrispaterson
chrispaterson marked this pull request as ready for review August 27, 2026 19:54
@chrispaterson
chrispaterson merged commit 4f28570 into paterson/GRAPH-3863/port-plugin-developer-guide Aug 27, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant