Point the docs regen at titaniumsdk.com - #313
Merged
Merged
Conversation
The API docs move to tidev/titanium-www, so the dispatch retargets there and carries this repo's name in the payload. The old dispatch sent nothing, which is why the regen had to check out all 17 source repos to work out what had changed; it now fetches only this one. Fires on a push touching apidoc/ and on a published release, rather than only on a merged pull request, so a direct push to master is no longer missed. The dispatch step itself moves into a reusable workflow in titanium-www so the payload shape is defined once for all 17 source repos. Also drops two things carried along for years: a full-history checkout that a lint does not need, and an `if:` guarding npm ci on a `node-cache` step that does not exist in this file.
Restores workflow_dispatch, which several of these repos had and the replacement dropped, removing the only way to force a regen by hand from the Actions tab. Adds a pull_request trigger so the lint job runs on a proposed change. Without it these PRs get no CI at all, and the Node bump from 16 to 24 would surface only after merge -- when a push to the default branch fails, the dispatch never fires, and nothing says so. notify is skipped on pull_request: a proposed change gets linted, not published.
notify no longer needs lint. Gating the dispatch on the lint job means an unrelated tooling problem stops the docs updating and nothing says so. ti.coremotion cannot run `npm ci` at all today -- its package-lock.json is out of sync with package.json, missing escape-string-regexp@1.0.5 -- so with the gate in place its docs would never regenerate again, silently. Its Regen Docs workflow has in fact never run once, and ti.map's last run failed in April. Genuinely malformed apidoc still cannot ship. The compile in titanium-www fails on unresolved references and schema violations and commits nothing, so the protection is downstream where it can see the whole corpus. The lint here is a second, advisory check and now reports independently.
Both pipelines now fire. The site currently being served keeps updating while the replacement is proven, and backing out is merging a revert rather than racing to restore a dispatch. The legacy job carries no payload because titanium-docs does not read one -- it rebuilds every source repo on any dispatch, which is the inefficiency titanium-www exists to replace. Marked for deletion once titaniumsdk.com is served from titanium-www.
From the review on titanium-sdk#14564, applied to all 17 repos so the template stays identical across them: - Job renamed back to `regen`, matching what was there before. - actions/checkout and actions/setup-node moved to v7. - Node 26. - Every step given a name. The setup-node suggestion as written would have produced two steps -- a bare `- name:` followed by a separate `- uses:` -- so it is applied as one named step on v7.
peter-evans/repository-dispatch v3 -> v4, matching the version bumps applied across titanium-www's own workflows so every file in the pipeline pins the same majors.
titanium-sdk carried `github.repository_owner == 'tidev'` and the module repos did not -- an inherited asymmetry, not a decision. Worse, this branch had it on the wrong job: once notify stopped depending on lint, guarding lint stopped guarding anything. A fork would skip the one job that is useful there and still run both dispatch jobs, which fail because a fork holds no dispatch token. The guard now sits on the two jobs that reach outside the repo, in all 17 repos. Forks lint their own apidoc changes, which is worth having, and produce no failing dispatch runs. It is about noise, not security. A fork has no REGEN_DOCS_GITHUB_TOKEN, and even with one the payload names the fork, which is not on titanium-www's allowlist -- that allowlist is the actual boundary.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of the titaniumsdk.com rebuild. The API docs pipeline gains a second destination,
tidev/titanium-www, while the existing one keeps running.What changes
tidev/titanium-wwwcarrying this repo's name in the payload. The existing dispatch sent nothing, so the regen had to check out all 17 source repos at full history on every trigger to work out what had changed. The new one fetches only this repo, shallow, sparse toapidoc/.tidev/titanium-docs, unchanged, as a second job. Both pipelines run in parallel so the site being served today stays current while the replacement is proven; backing out is merging a revert.apidoc/**and on a published release, rather than only on a merged pull request — a direct push is no longer missed.titanium-www, so the payload shape is defined once for all 17 source repos rather than copied into each.Why
notifydoes not depend onlintGating the dispatch on the lint job means an unrelated tooling problem stops the docs updating and nothing says so.
ti.coremotioncannot runnpm ciat all today — its lockfile is out of sync with itspackage.json— and with the gate in place its docs would silently never regenerate.Malformed apidoc still cannot ship: the compile in
titanium-wwwfails on unresolved references and schema violations and commits nothing, which is the right place for that check since it can see the whole corpus.Cleanups
fetch-depth: 0removed — a lint does not need full history.if: steps.node-cache.outputs.cache-hit != 'true'removed; there is nonode-cachestep in this file, so the condition never did anything. Replaced with real npm caching.npm ciandlint:docson a current Node against repos previously pinned to 16.pull_requesttrigger soapidoc/changes get linted before merge.notifyis skipped on pull requests — a proposed change gets linted, not published.