Skip to content

Template hygiene: empty .vale.ini, release-info-test.sh fails in doc mode, stale MIGRATION.md checklist #152

Closed

Description

@wmat

Three small things found while migrating riscv/docs-dev-guide onto the template
in doc mode (riscv/docs-dev-guide#168). Filing together since each is a one-liner;
happy to split.

1. .vale.ini is committed empty (0 bytes)

$ git ls-files -s .vale.ini
100644 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 0	.vale.ini

e69de29 is git's empty blob. UPGRADING.md §A lists .vale.ini as
template-owned — "overwrite them without reading the diff closely" — so a repo
following the upgrade procedure literally will silently wipe its Vale config.

docs-dev-guide had a real 1008-byte config (StylesPath, Packages pulling
riscv-vale, Vocab = riscv-vocab, BasedOnStyles). We skipped the copy
deliberately, but only because the size difference was noticed.

Either ship the intended config, or move .vale.ini to the Shared files
table so the guidance stops telling people to overwrite it.

2. tests/release-info-test.sh cannot pass in a doc-mode repo

$ bash tests/release-info-test.sh          # in a repo with .docmode = doc
55 passed, 23 failed

$ mv .docmode .docmode.bak && bash tests/release-info-test.sh
78 passed, 0 failed

All 23 failures are phase assertions (display v0.8 expected Stabilized, got
'') — correct doc-mode behaviour per release-info.sh's neutralization. The
suite creates its own temp repo for the .docmode cases (lines 147–181) but the
phase cases run against the repo root, so they inherit whatever mode that repo is
in.

Nothing runs the suite in CI, so this is a papercut rather than a breakage — but
it does mean a doc-mode maintainer cannot use it as a regression check. Setting
mode explicitly per assertion, or running the phase block in a forced-spec temp
repo, would fix it.

3. MIGRATION.md's doc-mode checklist is stale

The "Doc mode" section asks the reader to hand-edit version-bot.yml:

a doc-mode version-bot.yml's milestone-pr job ... 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).

Both are already on main — tag-version exports mode, and milestone-pr
already reads:

if: needs.tag-version.outputs.milestone_transition == 'true' && needs.tag-version.outputs.mode == 'spec'

The instruction predates PR #150 landing them. As written it invites someone to
re-apply an edit that is already there.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions