diff --git a/.gitignore b/.gitignore index 8446531..f66a516 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,9 @@ **/.DS_Store # Local Antora preview tooling (see package.json / ANTORA.md Phase 5) /node_modules/ +# Vale style packages, downloaded into StylesPath by `vale sync` at lint time +# (see .vale.ini). Fetched on every run, never committed. +/.github/styles/ /.cache/ # Generated diagram/math artifacts (kroki fetch + asciidoctor-mathematical); # regenerated every build, never committed. diff --git a/.template-version b/.template-version index 1493d10..703eacf 100644 --- a/.template-version +++ b/.template-version @@ -4,9 +4,10 @@ # v* git tags created by the version-bot.yml workflow. # # Baseline is template main rather than a release tag: doc mode (the posture -# this repo runs in, see .docmode) landed in template PR #150 and is not in any -# tagged release yet. The template's tag namespace also mixes real releases with -# version-bot test tags, so the SHA is the authoritative record. +# this repo runs in, see .docmode) landed in template PR #150, and the fixes for +# the issues this repo raised (#151, #152) landed in PRs #153 and #154. None of +# that is in a tagged release yet. The template's tag namespace also mixes real +# releases with version-bot test tags, so the SHA is the authoritative record. template_ref: main -template_sha: 74566374080a11fd7abe482b1246a87a12158f8b -upgraded_on: 2026-09-09 +template_sha: 5a3a96eb1d9bab1332c74ebdda046a3d0b80030f +upgraded_on: 2026-09-10 diff --git a/.vale.ini b/.vale.ini index cd7c8bd..f16499f 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,34 +1,44 @@ +# Vale configuration for this specification repository. +# +# Vale runs on every pull request via .github/workflows/vale-linting.yml, which +# calls the reusable workflow in riscv-admin/riscv-vale. That action reads THIS +# file from the repository under test -- it does not supply a config of its own, +# so an empty or missing .vale.ini means Vale runs and lints nothing. +# +# Ownership (see UPGRADING.md, "Shared files"): `StylesPath` and `Packages` are +# template-owned -- they point at the shared RISC-V style package and should be +# taken from the template on every upgrade. `BasedOnStyles`, `Vocab`, and the +# rule disables at the bottom are YOURS: a task group that has agreed on its own +# vocabulary or has switched a rule off should keep those lines across upgrades. +# +# `Packages` are downloaded into `StylesPath` by `vale sync` at lint time and are +# never committed -- .gitignore excludes .github/styles/ for that reason. + StylesPath = .github/styles -minAlertLevel = suggestion +MinAlertLevel = suggestion IgnoredScopes = code, tt, img, url, a, body.id SkippedScopes = script, style, pre, figure, code, tt, blockquote, listingblock, literalblock -Packages = RedHat, AsciiDoc, https://github.com/riscv-admin/riscv-vale/releases/latest/download/riscv.zip, https://github.com/riscv-admin/riscv-vale/releases/latest/download/config.zip +Packages = AsciiDoc, https://github.com/riscv-admin/riscv-vale/releases/latest/download/riscv.zip, https://github.com/riscv-admin/riscv-vale/releases/latest/download/config.zip Vocab = riscv-vocab [*.adoc] -BasedOnStyles = Vale, RedHat, riscv, AsciiDoc - -#[*.md] -#BasedOnStyles = Vale, RISCV-Vale, AsciiDoc - -# Ignore code surrounded by backticks or plus sign, parameters defaults, URLs. -TokenIgnores = (\x60[^\n\x60]+\x60), ([^\n]+=[^\n]*), (\+[^\n]+\+), (http[^\n]+\[) - -# Match INI files. See: https://docs.errata.ai/vale/scoping -#[*.ini] -#BasedOnStyles = Vale, RISCV-Vale - -# Disabling rules (NO) -#RedHat.CaseSensitiveTerms = NO -#RedHat.ConfigMap = NO -#RedHat.Definitions = NO -#RedHat.Slash = NO -#RedHat.Spacing = NO -#RedHat.Spelling = NO -#RedHat.TermsSuggestions = NO - -#with: -# files: src/*.adoc +# `riscv` is the RISC-V house style; `AsciiDoc` checks AsciiDoc structure. The +# generic `Vale` style (Vale.Spelling, Vale.Repetition) is deliberately NOT +# enabled: specification prose is dense with mnemonics, CSR names and extension +# names that its dictionary does not carry, and it reports 401 errors on this +# template's own sample content. To opt in, add `Vale` to the list below and +# expect to grow `Vocab` alongside it. +BasedOnStyles = riscv, AsciiDoc + +# Ignore code surrounded by backticks or plus signs, parameter defaults, URLs, +# and AsciiDoc macro patterns like csr:mseccfg[mlpe]. +TokenIgnores = (\x60[^\n\x60]+\x60), ([^\n]+=[^\n]*), (\+[^\n]+\+), (http[^\n]+\[), (\w+:\w+\[[^\]]*\]) + +# Disabled rules. riscv.Slash flags "and/or" style constructions and +# riscv.SentenceLength flags long sentences; both are advisory and produce heavy +# noise on specification prose. +riscv.Slash = NO +riscv.SentenceLength = NO diff --git a/MIGRATION.md b/MIGRATION.md index 7fd771d..2aa3358 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -69,11 +69,12 @@ preface, the phase/milestone attributes, and `SPEC_STATE.md` tracking. `phase-floor-version` all resolve to `""` in doc mode automatically. - [ ] In Step 3/4's `build-pdf.yml`/`version-bot.yml`, the `target_phase` enum and milestone gating stay as-is (they're pure version arithmetic, - not ratification), but a doc-mode `version-bot.yml`'s `milestone-pr` - job (which regenerates `SPEC_STATE.md`) should be gated the same way - upstream's is: add `&& needs.tag-version.outputs.mode == 'spec'` to its - `if:` (and add a `mode` output to `tag-version`, from - `release-info.sh mode`). + not ratification). No doc-mode edit is needed on top of that: upstream's + `version-bot.yml` already exports a `mode` output from `tag-version` + (`release-info.sh mode`) and already gates the `milestone-pr` job -- + the one that regenerates `SPEC_STATE.md` -- on + `needs.tag-version.outputs.mode == 'spec'`. Take the upstream file as + written and the gate comes with it. Do not re-apply that edit by hand. - [ ] Skip Step 5's Document State preface and phase-attribute defaults entirely — a doc-mode top-level `.adoc` needs neither; the upstream file already guards them behind `ifndef::doc-mode[]`. diff --git a/UPGRADING.md b/UPGRADING.md index 4d39349..e41dcf0 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -215,7 +215,7 @@ history required: git checkout $TARGET -- \ scripts/ tests/ \ .github/workflows/ .github/dependabot.yml \ - .pre-commit-config.yaml .vale.ini docker-compose.yml \ + .pre-commit-config.yaml docker-compose.yml \ ANTORA.md MIGRATION.md ARC_SUBMISSION.md ``` @@ -590,7 +590,6 @@ tests/release-info-test.sh .github/workflows/vale-linting.yml .github/dependabot.yml .pre-commit-config.yaml -.vale.ini docker-compose.yml ANTORA.md MIGRATION.md @@ -629,6 +628,7 @@ keeping your own values from this table. | `CHANGELOG.md` | Yours; see section 6 for how to log the upgrade itself | | `.gitignore` | Usually identical; the template adds entries as new generated artifacts appear | | `.gitmodules` | Usually identical — check rather than assume | +| `.vale.ini` | `BasedOnStyles`, `Vocab`, and any rule you have switched off; `StylesPath` and `Packages` are template-owned | | `src/.adoc` | Your `include::` lines only; see below | #### The one file that is both diff --git a/scripts/build-pages-site.sh b/scripts/build-pages-site.sh index e9669db..5177336 100755 --- a/scripts/build-pages-site.sh +++ b/scripts/build-pages-site.sh @@ -176,4 +176,35 @@ antora_bin="$repo_root/node_modules/.bin/antora" [ -x "$antora_bin" ] || antora_bin="npx antora" $antora_bin --fetch "$generated_playbook" +# The shared RISC-V UI bundle links to `home/index.html` from every page: the +# header logo, the "RISC-V Specifications" breadcrumb, and the nav-tree root. +# That path is the `home` component on the central docs.riscv.org site, which a +# single-repo build does not have -- so without this file every page here 404s +# on the logo and the breadcrumb. +# +# This CANNOT be fixed in the generated playbook. Of the three references, only +# partials/nav.hbs is configurable (via site.keys.toc_home_link_path); +# partials/header-content.hbs and partials/breadcrumbs.hbs hardcode the path. +# Emitting the file is the only lever a standalone build has. +# +# Antora has already written the site-root index.html -- a redirect to +# `start_page` -- so one hop from here lands the reader on the component start +# page, which is where the central site's `home` component would have taken +# them. Guarded so a repo that genuinely ships its own `home` component keeps it. +if [ -e "$output_dir/home/index.html" ]; then + echo "==> Keeping existing home/index.html (this build has a 'home' component)" +else + echo "==> Emitting home/index.html redirect for the shared UI's fixed links" + mkdir -p "$output_dir/home" + cat > "$output_dir/home/index.html" <<'HTML' + + + + + +Redirect Notice +

This documentation is here.

+HTML +fi + echo "==> Done: $output_dir" diff --git a/tests/release-info-test.sh b/tests/release-info-test.sh index de53cb1..e024f1e 100755 --- a/tests/release-info-test.sh +++ b/tests/release-info-test.sh @@ -9,7 +9,26 @@ set -uo pipefail here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -RI="$here/../scripts/release-info.sh" + +# These assertions describe SPEC-mode behaviour, and release-info.sh resolves +# .docmode relative to its OWN location (repo_root = script dir/..), not the +# caller's cwd. Running the script in place would therefore inherit whatever +# mode THIS repository is in -- in a doc-mode repo every phase/display/floor +# assertion below would compare against the empty string that doc mode is +# supposed to return, and the suite would report failures for correct behaviour +# (see issue #152). +# +# So drive a copy of the script from a scratch repo with no .docmode: mode is +# pinned to spec no matter where the suite runs. The doc-mode assertions at the +# bottom keep their own scratch repo and opt IN to doc mode explicitly, which is +# the same pattern -- this just applies it to the whole suite. Nothing here +# needs the template's git history: the two blocks that DO need a repo (the +# untagged-build and .docmode sections) build their own. +specrepo="$(mktemp -d)" +mkdir -p "$specrepo/scripts" +cp "$here/../scripts/release-info.sh" "$specrepo/scripts/release-info.sh" +RI="$specrepo/scripts/release-info.sh" +trap 'rm -rf "$specrepo"' EXIT pass=0 fail=0