Skip to content

fix(docs): publish the documentation from development, not a stale branch - #428

Merged
rubenvdlinde merged 3 commits into
developmentfrom
fix/docs-publish-from-development
Aug 24, 2026
Merged

fix(docs): publish the documentation from development, not a stale branch#428
rubenvdlinde merged 3 commits into
developmentfrom
fix/docs-publish-from-development

Conversation

@rubenvdlinde

Copy link
Copy Markdown
Contributor

What

Points this app's documentation workflow at development instead of a branch
called documentation.

Why the docs have been frozen

The workflow triggered on push: branches: [documentation]. That branch
exists
— which is why nothing ever looked broken — but nobody updates it:

app documentation last commit development is ahead by
larpinq 2026-05-19 594 commits
buildiq 2026-07-09 980 commits

So the pipeline has been faithfully republishing a months-old snapshot and
reporting success every time.

This is why larpinq.conduction.nl still says "LarpingApp" and
decidiq.conduction.nl still says "Decidesk", while both repos' docs sources
have said the new name since the app-id rename merged. The rename was never
missed in the docs — the docs were publishing from somewhere else.

Not an outlier

Four of the twelve fleet apps (dossiq, integriq, stackiq, thematiq) already point
at development. Seven were on documentation. This brings them in line.

The other half

Pairs with ConductionNL/.github#555, which made the reusable workflow publish
to the Cloudflare Worker that actually serves each docs host — previously it
wrote gh-pages and nothing read it, then printed "Deployment completed" with
the gh-pages commit.

Both halves are needed, and they fail differently:

fixed by
where the docs go .github#555 — the Worker, not gh-pages
which commit they come from this PR — development, not a stale branch

Measured proof the pair works: buildiq's docs were rebuilt and published by hand
after #555 merged, and buildiq.conduction.nl now serves "Buildiq, no-code app
builder inside Nextcloud" with zero occurrences of the old name, where it had
been serving a 26 June build.

…anch

This workflow triggered on `push: branches: [documentation]`. That branch
exists, which is why nothing ever looked broken — but nobody updates it. Its
last commit predates most of this year's work: larpinq 19 May (development is
594 commits ahead), buildiq 9 July (980 ahead).

So the docs pipeline has been faithfully republishing a months-old snapshot, and
reporting success every time. It is the reason larpinq.conduction.nl still says
"LarpingApp" and decidiq.conduction.nl still says "Decidesk" while both repos'
docs sources have said the new name since the app-id rename merged. The rename
was never missed in the docs — the docs were publishing from somewhere else.

Four of the twelve fleet apps (dossiq, integriq, stackiq, thematiq) already point
at `development`. This brings the rest in line.

Pairs with ConductionNL/.github#555, which made the reusable workflow publish to
the Cloudflare Worker that actually serves the host — previously it wrote
gh-pages and nothing read it. Both halves are needed: one fixes WHERE the docs go,
this one fixes WHICH COMMIT they come from.
The trigger fix in this PR makes the docs workflow run. This commit makes
the run reach the edge.

`worker-name` was never passed, so the callee derived it from `cname`.
Since the app-id rename `cname` is the NEW host, and the worker that
actually holds the custom domains is still named after the OLD app id.
The derived name therefore points at a worker that does not exist —
deploying it CREATES a second worker while both custom domains keep
routing to the original. Every deploy green, reaching nobody, with the
live-site verification added in ConductionNL/.github#555 as the only
thing that would ever have noticed.

Pinning the name also decouples the worker from `cname`, so the docs host
can move to the new subdomain later without silently forking the worker.

Measured today: the live host still serves the pre-rename title, which is
the staleness this PR chain exists to end.
@rubenvdlinde

Copy link
Copy Markdown
Contributor Author

Scope grew by one commit after auditing what a successful run of this workflow would actually have done.

Fixing the trigger makes this workflow run. It would then have deployed to keepiq.conduction.nldoriath-docs — the worker name the callee derives from cname when worker-name is not passed. That worker does not exist. Both custom domains for this site live on doriath-docs.

Deploying the derived name does not fail. It creates a second worker, while both custom domains keep routing to the original — so every deploy is green and reaches nobody. The live-site <title> verification added in ConductionNL/.github#555 is the only instrument that would ever have caught it.

worker-name is now pinned explicitly. That also decouples the worker from cname, so the docs host can move to the new subdomain later without silently forking the worker.

@github-actions

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/keepiq @ c40375a

Check PHP Vue Security License Tests
lint ⏭️
phpcs ⏭️
phpmd ⏭️
psalm ⏭️
phpstan ⏭️
phpmetrics ⏭️
eslint ⏭️
stylelint ⏭️
build ⏭️
composer ⏭️ ⏭️
npm ⏭️ ⏭️
app:check-code ⏭️
info.xml ⏭️
REUSE ⏭️
PHPUnit
Newman
Playwright
Hydra gates

Quality workflow — 2026-08-24 09:25 UTC

Download the full PDF report from the workflow artifacts.

The docs build FAILS, and has been failing — it was simply never run,
because the workflow triggered on a branch nobody updates. Making the
trigger correct surfaced it on the first run.

  Error: MDX compilation failed for application-secret-requests.md
  Cause: Expected a closing tag for `<date>` (27:39-27:45)

`<date>` was written as a plain-English placeholder inside a table cell.
MDX reads it as an opening JSX tag, finds no closing tag, and aborts the
whole client bundle — so no page of this site could publish, whatever the
workflow did.

Backticks the two placeholders. They now render as code, which is what a
placeholder should look like anyway, and the sentence is unchanged.

Verified locally: npm ci --legacy-peer-deps && npm run build now exits 0
with all 10 AI-baseline checks passing.
@rubenvdlinde

Copy link
Copy Markdown
Contributor Author

One more commit. Once the trigger was fixed the workflow ran for the first time — and the docs build failed:

Error: MDX compilation failed for docs/application-secret-requests.md
Cause: Expected a closing tag for `<date>` (27:39-27:45)
[ERROR] Client bundle compiled with errors therefore further build is impossible.

<date> was written as a plain-English placeholder in a table cell. MDX reads it as an opening JSX tag, finds no closing tag, and aborts the entire client bundle — so no page of this site could publish, whatever the workflow did.

This was invisible for as long as the workflow never ran. Backticked the two placeholders; they now render as code, which is what a placeholder should look like anyway, and the sentence is unchanged.

Verified locally: npm ci --legacy-peer-deps && npm run build exits 0, all 10 AI-baseline checks pass.

@github-actions

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/keepiq @ 6c91e55

Check PHP Vue Security License Tests
lint
phpcs
phpmd
psalm
phpstan
phpmetrics
eslint
stylelint
build
check-manifest
test-l10n
format
check-l10n-js
check-schema-l10n
composer ✅ 111/111
npm ✅ 550/550
app:check-code ⏭️
info.xml
REUSE
PHPUnit
Newman
Playwright
Hydra gates

Quality workflow — 2026-08-24 09:50 UTC

Download the full PDF report from the workflow artifacts.

@github-actions

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/keepiq @ d76bfb2

Check PHP Vue Security License Tests
lint
phpcs
phpmd
psalm
phpstan
phpmetrics
eslint
stylelint
build
check-manifest
test-l10n
format
check-l10n-js
check-schema-l10n
composer ✅ 111/111
npm ✅ 550/550
app:check-code ⏭️
info.xml
REUSE
PHPUnit
Newman
Playwright
Hydra gates

Quality workflow — 2026-08-24 10:49 UTC

Download the full PDF report from the workflow artifacts.

@rubenvdlinde
rubenvdlinde merged commit c1dc58b into development Aug 24, 2026
48 checks passed
@rubenvdlinde
rubenvdlinde deleted the fix/docs-publish-from-development branch August 24, 2026 15:51
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