Migrate onto docs-spec-template (doc mode) by wmat · Pull Request #168 · riscv/docs-dev-guide

Bill Traynor (wmat) · 2026-09-09T20:42:52Z

Finishes the migration PR #165 started, so this repo looks and behaves as if it
had been seeded from docs-spec-template, at template main @7456637.

Why

docs-dev-guide was never seeded from the template — it predates it by ten
months (created 2021-03-04 vs 2022-01-07; template_repository: none).

PR #165 hand-copied the template's content layer. The evidence is
unambiguous: antora-playbook.yml is byte-identical to the template's but for
three lines, .gitignore is byte-identical, and package.json carries the
template's description verbatim. It left behind the build layer — scripts/,
ANTORA.md, and every template workflow.

That is the direct cause of the current breakage. deploy-website.yml (fb1578a)
was copied from this same template and calls ./scripts/build-pages-site.sh,
which has never existed here. It has failed with exit 127 on every push to
main since it was added. The .gitignore on main has been advertising that
script since #165 — the reference arrived, the file never did.

What this does

The repo runs in doc mode, the template's supported posture for non-ratified
documentation (MIGRATION.md §"Doc mode", which names this repo as its worked
example). Doc mode keeps the PDF target, the Antora site, and version identity
from semver tags; it strips only the ratification layer.

Five commits, following the template's own UPGRADING.md §A file-ownership split:

Template-owned files taken wholesale — scripts/, tests/, the six
workflows, ANTORA.md/MIGRATION.md/ARC_SUBMISSION.md/UPGRADING.md, plus
.docmode.
Shared files merged by hand — Makefile, antora.yml, package.json,
.gitmodules. Our DOCS, BUILD_DIR, git_sha.adoc rule, name, title
and asamBibliography are kept; the template's version plumbing is taken.
Cover page and revision scaffolding from the template.
Workflow cutover — publish-site.yml replaces both static.yml and
deploy-website.yml; vale-linting.yml replaces vale-using-reusable.yml.
.template-version baseline record, so the next upgrade is a diff rather
than an investigation.

Fixed along the way

page-pdf_url dropped. The UI bundle path-joins it rather than treating it
as absolute, so it rendered on all 16 pages as
/reference/docs-guide/v0.20/https://github.com/... — broken twice over.
Malformed image attribute on the cover: [id="riscvlogo"xs,...] was missing
a comma and role=, silently dropping the size class.
The PDF title page never showed a version. src/docs-dev-guide.adoc
declared no revision attributes at all, which defeated the version lockstep this
tooling exists for. It now renders v0.20-<sha>, 2026-09-09.

Verification

Check	Result
`release-info.sh mode`	`doc`
`tests/release-info-test.sh`	78/78 (spec mode)
`stamp-antora-version.sh`	accepts `antora.yml`; "doc mode: phase surface not stamped"
`npm run preview` (Antora 3.2.0)	exit 0
`scripts/build-pages-site.sh`	exit 0, vendors cover logo, skips all 5 junk tags
`make build-container`	PDF + HTML build

Known regression — please read

scripts/build-pages-site.sh does not emit home/index.html, and the shared
UI bundle links to it from every page. I extracted the bundle to check whether it
is configurable:

nav.hbs — configurable via site.keys.toc_home_link_path
header-content.hbs — hardcoded {{siteRootPath}}/home/index.html
breadcrumbs.hbs — hardcoded

Two of the three cannot be configured away, so the header logo and the
"RISC-V Specifications" breadcrumb will 404 on all 16 pages. The stopgap
static.yml from #167 emitted that redirect, so this is a regression against
what is live today.

This is a template bug affecting every seeded repo that publishes to Pages, not
something specific to us. Per UPGRADING.md — local edits to template-owned files
"belong upstream instead" — it is reported upstream as
riscv/docs-spec-template#151 rather than patched here.

Also reported upstream (riscv/docs-spec-template#152)

The template ships a 0-byte .vale.ini. Ours is a real config, so it was
deliberately not overwritten.
tests/release-info-test.sh fails 23 phase assertions when run from a doc-mode
repo root (78/78 in spec mode). Nothing runs it in CI.
MIGRATION.md's doc-mode checklist asks for version-bot.yml changes that are
already implemented upstream — the checklist is stale.

Unrelated wart worth knowing

This repo has a git tag named main, which shadows the branch: git log main
warns refname 'main' is ambiguous and resolves to the tag. There is a vmain
tag too. Neither is a valid version, so release-info.sh filters them and no tag
cleanup was needed for this PR — but the main tag is worth deleting separately.

🤖 Generated with Claude Code

docs-dev-guide was never seeded from docs-spec-template -- it predates it by ten months. PR #165 hand-copied the template's content layer (antora-playbook.yml, .gitignore, package.json) but left the build layer behind, which is why deploy-website.yml calls a scripts/build-pages-site.sh that has never existed here. Take the template-owned files wholesale from docs-spec-template main @7456637, per UPGRADING.md "Which files are whose", and switch the repo to doc mode with a .docmode file. Doc mode is the template's supported posture for non-ratified documentation; it keeps the PDF target, the Antora site and version identity from semver tags, and drops only the ratification layer. Not taken: * .vale.ini -- the template ships an empty (0-byte) file; ours is a real config. Reported upstream rather than forked. * scripts/update-spec-state.sh and SPEC_STATE.md -- ratification-only. tests/release-info-test.sh passes 78/78 in spec mode but fails 23 phase assertions when run from a doc-mode repo root, because it hardcodes spec-mode expectations for the repo it runs in. Nothing runs it in CI. Also reported upstream. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: Bill Traynor <wmat@riscv.org>

Shared files carry template structure and this repo's own values on the same lines, so they are merged rather than copied (UPGRADING.md "Shared files"). Makefile: take the template's version/date plumbing (VERSION from release-info.sh, DATE_STAMP, VERSION_NUM), the DOC_MODE switch, the stamp-antora target and the versioned PDF name. Keep this repo's DOCS, BUILD_DIR indirection and the git_sha.adoc rule, which the template has no equivalent for. In doc mode the Makefile passes a single -a doc-mode='doc' marker instead of the phase attribute set. antora.yml: keep name/title/page-group/asamBibliography, adopt the template's structure, and add doc-mode plus the cover-logo indirection that build-pages-site.sh needs for single-repo builds. Doc mode stamps exactly version, page-revnumber and page-revdate -- stamp-antora-version.sh requires those three and no phase keys. Also drop page-pdf_url. The UI bundle path-joins it rather than treating it as absolute, so it rendered on all 16 pages as /reference/docs-guide/v0.20/https://github.com/... -- broken twice over. The template has no such key. package.json: take the template's Antora 3.1.15 -> 3.2.0 bump and regenerate the lockfile with npm install --package-lock-only. Verified: stamp-antora-version.sh accepts the new antora.yml and reports "doc mode: phase surface not stamped"; the PDF target resolves to build/docs-dev-guide-v0.20-20260909.pdf. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: Bill Traynor <wmat@riscv.org>

modules/ROOT/pages/index.adoc hardcoded both the logo resource and the version line, so a stamped antora.yml had no effect on what the cover actually showed. Switch to the template's pattern: {cover-logo}, which antora.yml maps to the shared `common` asset and build-pages-site.sh rewrites to a vendored copy for single-repo builds, and {page-revnumber}/{page-revdate}, which stamp-antora-version.sh drives. This also fixes a malformed image attribute list -- [id="riscvlogo"xs,...] was missing the comma and role=, so the size class was silently dropped. src/docs-dev-guide.adoc declared no revision attributes at all, so the PDF title page never showed a version. Add the template's ifndef fallbacks and :revinfo:. The Makefile already passes -a revnumber/-a revdate from release-info.sh, so these only apply to a bare asciidoctor run. Doc mode means no phase attribute defaults are needed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: Bill Traynor <wmat@riscv.org>

Three workflows are superseded by the template-owned set adopted earlier in this branch: static.yml -- the stopgap Antora build added in #167 to get the site publishing again. publish-site.yml does the same job with version resolution, release-tag publishing and a pinned Kroki service container instead of public kroki.io. deploy-website.yml -- added in fb1578a from this same template, but without the scripts/ directory it calls. It has failed with exit 127 on every push since, and is byte-for-byte the workflow publish-site.yml now provides, with its dependencies present. vale-using-reusable.yml -- identical in content to the template's vale-linting.yml; only the filename differed. That leaves one Pages workflow rather than two racing for the same concurrency group, and the workflow set now matches the template exactly. No change was needed to version-bot.yml: the doc-mode gating MIGRATION.md describes (a mode output on tag-version, and && mode == 'spec' on milestone-pr) is already implemented upstream, so the SPEC_STATE.md job cannot fire here. That is also why scripts/update-spec-state.sh is deliberately absent. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: Bill Traynor <wmat@riscv.org>

UPGRADING.md section 1.3: nothing reads this file, but it is the only record of which template version the tooling came from, which turns the next upgrade into a diff rather than an investigation. Baseline is template main @7456637 rather than a release tag, because doc mode landed in template PR #150 and has not been tagged yet. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: Bill Traynor <wmat@riscv.org>

+
+jobs:
+  call-reusable-vale-workflow-in-riscv-vale-repo:
+    uses: riscv-admin/riscv-vale/.github/workflows/vale-reusable.yml@main


The new content-source gate caught this: "target of xref not found: spec-sample:page.adoc". Line 47 shows an Antora cross-reference as an example of the syntax, but backticks alone do not stop AsciiDoc from substituting macros inside an inline code span, so Antora tried to resolve it as a real xref against a component (spec-sample) that only exists in the template. The identical xrefs further down the file are fine -- they sit inside a [source,adoc] listing block, which is verbatim. Wrap it in a + passthrough so it renders literally. Pre-existing since PR #165; the gate added in this branch is what surfaced it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: Bill Traynor <wmat@riscv.org>

Bill Traynor (wmat) and others added 5 commits September 9, 2026 16:22

github-advanced-security Bot found potential problems Sep 9, 2026

View reviewed changes

Comment thread .github/workflows/vale-linting.yml

jobs:

call-reusable-vale-workflow-in-riscv-vale-repo:

uses: riscv-admin/riscv-vale/.github/workflows/vale-reusable.yml@main

Bill Traynor (wmat) self-assigned this Sep 9, 2026

Bill Traynor (wmat) requested a review from Kersten Richter (kersten1) September 9, 2026 21:10

Kersten Richter (kersten1) merged commit bd51fba into main Sep 9, 2026
8 checks passed

This was referenced Sep 9, 2026

Restore the template's front and back matter #169

Merged

Upgrade to docs-spec-template 5a3a96e (fixes home/index.html 404s) #170

Merged

Navigation Menu

Repository navigation

Migrate onto docs-spec-template (doc mode) - #168

Migrate onto docs-spec-template (doc mode)#168
Kersten Richter (kersten1) merged 6 commits into
mainfrom
chore/template-migration

Bill Traynor (wmat) commented Sep 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Bill Traynor (wmat) commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What this does

Fixed along the way

Verification

Known regression — please read

Also reported upstream (riscv/docs-spec-template#152)

Unrelated wart worth knowing

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Bill Traynor (wmat) commented Sep 9, 2026 •

edited

Loading