Low priority — the API docs are rarely used and the build issues are harmless today — but worth capturing so it isn't forgotten.
Root issue: the jsdoc build emits warnings/errors
npm run build (jsdoc over the jellyrock source) currently produces build warnings/errors. Because of that, both ci.yml and update.yml run it as npm run build || true (there's already a TODO noting this), so the build can never fail the pipeline. Fixing those warnings/errors is the prerequisite for everything below.
Why it matters (the downstream fragility)
Until the build is clean and || true can be removed, the deploy shape is fragile:
deploy.yml rsyncs the committed docs/ artifact — it does not build on deploy.
ci.yml build can't fail (|| true), so a broken/partial build is invisible.
update.yml regenerates + commits docs/ only on repository_dispatch: code-update from jellyrock/jellyrock, not when api-docs config changes — and it also builds with || true, so it could commit empty/partial docs.
Net effect: a config change (e.g. jsdoc.json) doesn't reach the live site until docs/ is regenerated, and a silently-broken build could still deploy.
How it surfaced
During the ADR-0006 first-party analytics migration (jellyrock/command-center), switching the tracker embed in jsdoc.json had no effect on live api.jellyrock.app — the deploy served the stale committed docs/. Needed a second PR to regenerate the artifact (#43 = config, #44 = artifact).
Suggested order
- Fix the jsdoc build warnings/errors (the actual work; low priority).
- Remove
|| true from ci.yml + update.yml so build failures are visible.
- Then harden the deploy — either build-on-deploy (stop committing
docs/) or gate the rsync deploy on a green build via workflow_run.
Steps 2–3 are cheap once step 1 is done. Org-deploy-consistency context: ADR-0004 / ADR-0005 in jellyrock/command-center.
Low priority — the API docs are rarely used and the build issues are harmless today — but worth capturing so it isn't forgotten.
Root issue: the jsdoc build emits warnings/errors
npm run build(jsdoc over thejellyrocksource) currently produces build warnings/errors. Because of that, bothci.ymlandupdate.ymlrun it asnpm run build || true(there's already a TODO noting this), so the build can never fail the pipeline. Fixing those warnings/errors is the prerequisite for everything below.Why it matters (the downstream fragility)
Until the build is clean and
|| truecan be removed, the deploy shape is fragile:deploy.ymlrsyncs the committeddocs/artifact — it does not build on deploy.ci.ymlbuild can't fail (|| true), so a broken/partial build is invisible.update.ymlregenerates + commitsdocs/only onrepository_dispatch: code-updatefromjellyrock/jellyrock, not when api-docs config changes — and it also builds with|| true, so it could commit empty/partial docs.Net effect: a config change (e.g.
jsdoc.json) doesn't reach the live site untildocs/is regenerated, and a silently-broken build could still deploy.How it surfaced
During the ADR-0006 first-party analytics migration (jellyrock/command-center), switching the tracker embed in
jsdoc.jsonhad no effect on liveapi.jellyrock.app— the deploy served the stale committeddocs/. Needed a second PR to regenerate the artifact (#43 = config, #44 = artifact).Suggested order
|| truefromci.yml+update.ymlso build failures are visible.docs/) or gate the rsync deploy on a green build viaworkflow_run.Steps 2–3 are cheap once step 1 is done. Org-deploy-consistency context: ADR-0004 / ADR-0005 in jellyrock/command-center.