docs: add a guide for upgrading a repo to a newer template version

[Bill Traynor (wmat)]

Why

A repository created with GitHub's Use this template starts a fresh history with no common ancestor shared with docs-spec-template. Git sees the two as unrelated projects, so there is no automatic three-way merge and no obvious way to pick up later toolchain improvements — new workflows, fixed build scripts, ARC compliance changes.

MIGRATION.md covers adopting the toolchain once. This covers keeping up with it over time.

What it recommends

Per-path git checkout template/<ref> -- <paths> rather than a merge: no shared history required, no conflicts, and the file tiering is enforced by which paths you type. The unrelated-histories merge and cherry-picking are documented as alternatives with their real costs.

Every path is sorted into three tiers:

• Template-owned — scripts/, .github/workflows/, reference docs. Take wholesale.
• Shared — Makefile, antora.yml, antora-playbook.yml, package.json. Hand-merge, keep your values.
• Spec-owned — modules/ROOT/, SPEC_STATE.md, MAINTAINERS.md. Never take upstream.

Two things worth reviewer attention

The src/<spec>.adoc exception. It is spec-owned by ownership but template-shaped by structure — the [preface] == Document State block, toc::[] and [index] placement, and the ifndef:: attribute defaults are all ARC compliance surface. It is the one file that must be diffed on every upgrade and never copied wholesale. A repo that skips it upgrades cleanly and then fails ARC on format rather than content.

A proposed .template-version convention. Downstream v* tags are specification versions minted by version-bot.yml, so nothing today records which template version a repo tracks. Without that baseline, every upgrade starts with archaeology. The guide is explicit that this file does not exist in the template yet — it only pays off if the template adopts it, so it is the main thing to agree or reject here.

The guide also notes that the semver release line (v1.0.0 → v4.0.4) currently lags main, with the Antora dual build, Pages publish, and PR preview artifact still under [Unreleased], and that the tag namespace is shared with version-bot test tags (vtest, v0.01, v1.0_rc1) — so it tells you to pin to a SHA rather than track a moving main.

Notes

• Docs only — no build, workflow, or script changes.
• Not linked from README.adoc yet; happy to add a line to its IMPORTANT block alongside the MIGRATION.md / ANTORA.md pointers if reviewers want it here rather than in a follow-up.

🤖 Generated with Claude Code

[Kersten Richter (kersten1)]

Left you lots.... I didn't finish it.

[Kersten Richter (kersten1)]

Not sure why anyone would care about this info in this section. I'd move out to the readme actually.

[Bill Traynor (wmat)]

Split this. Added a pointer to the README IMPORTANT block alongside the existing MIGRATION.md / ANTORA.md lines, which is where someone actually discovers the guide exists.

The comparison table itself moved to the back of the document as Reference section D rather than into the README — the README block is three sentences and a four-row table would swamp it. If you would rather the table live in the README too, say so and I will move it.

[Bill Traynor (wmat)]

Thanks — this was exactly the review the document needed. Pushed 2e47414 addressing all 48 comments.

Heads up before you pick the review back up: the document is reordered, so your remaining unreviewed comments will not line up with the new line numbers. The procedure now comes first, and the explanation moved to the back.

Structure

The procedure-first point came up about six times, so I took it wholesale:

Before	After
1. Why this needs a procedure	1. Before you begin
2. The file contract	2. Upgrade
3. One-time setup	3. Verify
4. The upgrade procedure	4. What upgrades tend to break
5–9	5. Rolling back / 6. When to upgrade
—	Reference — A. Which files are whose, B. Why this needs a procedure, C. Other approaches, D. The other guides

"One-time setup" became "Before you begin" with your framing, and what was step 4 is now step 1.

Things you caught by actually running it

These were the most valuable comments in the review:

• git rev-parse was documented after the heredoc that needs its output. Reordered, and the file now says which two values to replace.
• UPGRADING.md in the checkout list. You are right that it cannot work until this merges — removed, with a note that it can be added once the template ships it in a release.
• The CHANGELOG diff returned nothing. That was the template's changelog, not yours, and the guide never said so. Now points at the file on GitHub and notes that an empty local diff is expected.
• "What do I want for a target? No clue." TARGET and BASELINE now have their own step that explains what each one is before any command uses them.
• The procedure never told you to push. It ended with changes in your working tree. There is now a step to commit, push, and open a PR.
• Terminal diffs. You hit this three times. Every diff step now offers a compare/<base>...<target> URL for the browser and leads with --stat.
• Baseline selection. Used your sample output more or less verbatim, including the tie-breaker.

Language

Dropped everything flagged as not translating: "mechanical instead of archaeological", "transplant", "quietly customized", "cheapest first", "ordered by how often they bite", "the file contract", "tractable", "dispatch". "By hand" is now "manually" throughout. The tier 1/2/3 numbering is gone entirely in favour of template-owned / shared / specification-specific, which also fixed the "why would anyone care" problem with the old section openers.

Explanatory comments moved out of the code blocks and into prose.

Five threads need your input

I replied inline rather than just editing on these:

1. .template-version vs .template — kept the longer name, explained why. This is the one thing in the PR that needs a decision rather than an edit.
2. Alternative strategies — cut to four lines marked explicitly unsupported, rather than removed.
3. The guides table — README now has a pointer; the table stayed at the back.
4. The ARC warning — reframed rather than dropped.
5. src/<spec>.adoc — moved into shared files as you asked.

No rush on the rest of the review — it is a different document now, so re-reading from the top is probably less work than continuing where you stopped.

[Bill Traynor (wmat)]

Review threads are cleared — all 36 outstanding threads are replied to and resolved, each one naming where the fix landed so you can spot-check rather than re-read.

One of them still needed a code change: git diff -- src/ in 2.6 was the only diff step the restructure missed, so your third "this also opens in the terminal" comment was still live. Fixed in 99ab209, which also drops the last surviving "mechanical application" phrasing in Reference A.

Two threads left open, because both are yours to call rather than mine to edit:

1. .template-version vs .template. The guide ships the longer name today, with a note that the file does not exist upstream yet. Nothing should get written into a downstream repo until this is settled, so it is the one thing blocking the guide from being actionable.
2. The guides comparison table — currently Reference D, with a pointer added to the README IMPORTANT block. Say the word and the table moves to the README too.

One thing worth flagging before you pick this back up: your review ran to the end of the old 460-line file, but the restructure made it 619 lines and reordered it. Sections 4–6 (What upgrades tend to break, Rolling back, When to upgrade) and Reference A–D are effectively unreviewed in their current form — the earlier comments on that material were about text that has since moved or been rewritten. That back half is where I would spend the next pass.

[Kersten Richter (kersten1)]

This command just sits there. I finally killed it.

[Bill Traynor (wmat)]

That should not happen and I would like to know what you saw. It runs in about a second here and ends with 64 passed, 0 failed. My guess is that it was blocked on a prompt rather than working: the test does git init on a throwaway repository and commits into it, so a global setting like commit.gpgsign=true can stop it dead waiting for a passphrase. Worth checking git config --global --get commit.gpgsign.

The guide now says what a passing run looks like and how to diagnose an apparent hang (bash -x tests/release-info-test.sh to see the last command). If it turns out to be something else on your machine, tell me what bash -x shows and I will document the real cause instead of my guess.

[Kersten Richter (kersten1)]

Is this always v4.0.0 or is it whatever version has the fewest differences? The one I'm testing now, v4.0.4 has the fewest so I'm assuming I use that?

[Bill Traynor (wmat)]

Whichever has the fewest — v4.0.0 was just what the sample output above happened to produce. Made that explicit: "Substitute your own baseline here — the sample output above happened to favour v4.0.0, but yours may be any of the releases, or template/main." So for your repo, v4.0.4.

[Kersten Richter (kersten1)]

I am not sure what this paragraph is telling me. I understand that I can have a very old repo and all should still be well for upgrading. But how do I know if the template's newest numbered release is missing work?

[Kersten Richter (kersten1)]

I'm assuming that when we get to a point that we can create a version, this para might make more sense?

[Bill Traynor (wmat)]

It was missing the actual answer to "how do I know". Added it as a How to tell paragraph: open the template's CHANGELOG.md and read the [Unreleased] section — anything listed there is on main but not in any numbered release. If nothing there matters to you, take the newest release and move on.

And yes, your second comment is exactly right. The section closes with: "Once the template's release line catches up with main, this section stops being necessary — [Unreleased] will be empty and the newest release will have everything." It is describing a temporary state of the template, not a permanent part of the procedure.

[Kersten Richter (kersten1)]

Not sure what "take the newest template code" means. maybe apply the latest template code?

[Bill Traynor (wmat)]

Changed to "applies the latest template code".

[Kersten Richter (kersten1)]

don't we always want them on the latest? I'd skip this and say if you need to be on a specific version of the template, contact help@riscv and then you can walk them through it. Just muddies the waters else.

[Bill Traynor (wmat)]

Took it. The paragraph now defaults to the latest and stops explaining the alternatives:

template/main applies the latest template code, which is what you normally want. If you pinned to a commit SHA in 1.4, use that SHA here instead. If you need to land on a specific older template version, contact help@riscv.org rather than working it out from this guide.

Kept the SHA line only because 1.4 sends some readers here with one in hand; that is still forward, not older.

[Kersten Richter (kersten1)]

not sure you need the last sentence as the first sentence of the next para says the same thing.

[Bill Traynor (wmat)]

Dropped.

[Kersten Richter (kersten1)]

maybe just changes are described? Skip the "in prose".

[Bill Traynor (wmat)]

Dropped "in prose".

[Kersten Richter (kersten1)]

Can you link them to it?

[Bill Traynor (wmat)]

Linked: "See Template-owned in the Reference for what to do about a local edit to a template-owned file."

[Kersten Richter (kersten1)]

while I appreciate this info, it is confusing because I sat and thought for a minute about what I needed to name "template" and then realized that I did that in the last command.

[Bill Traynor (wmat)]

Right — the sentence was explaining the command above but read like a new instruction. It is now phrased as an explanation: "The remote is named template rather than the more usual upstream because if your repository is also a fork of something else, upstream will already be taken."

[Kersten Richter (kersten1)]

I'm not sure this heading is helpful. Would someone know what they need? Maybe call it Optional and Find out what is in the changelog or something like that.

[Bill Traynor (wmat)]

Retitled to 1.4 Optional: check whether the newest release has what you need, which says up front that it is skippable and what the check is.

[Kersten Richter (kersten1)]

I'd make this optional too. I mean, it was all gobbledigook to me and I helped with some of it.

[Bill Traynor (wmat)]

Done — now 2.2 Optional: see what changed, opening with "You can skip this section and go straight to 2.3. It is here for when you want to know what is arriving before you take it."

[Kersten Richter (kersten1)]

This is slightly confusing because I am comparing the spec-sample.adoc file but the changes need to go into my src/.adoc file. I mean, I can copy them into a spec-sample.adoc file but then I still need to update my src/.adoc file so not sure why I would do that. Am I wrong/

[Bill Traynor (wmat)]

You are not wrong, and the guide was not saying this clearly. The diff is of the template's spec-sample.adoc because that is the only place the scaffolding changes are visible — but the edits go into your own src/<your-spec>.adoc, by hand. You never touch a spec-sample.adoc in your repo.

Section 2.6 now says that before the first command:

What you are comparing, and why. The file you diff is the template's own sample assembler, src/spec-sample.adoc, at your two refs. That tells you what scaffolding changed upstream. You then make the same change by hand in your own src/<your-spec>.adoc. You never copy spec-sample.adoc over your own file: it carries the sample specification's chapters and its own spec_short value, not yours.

[Kersten Richter (kersten1)]

Can you put these in a bulleted list to make it easier to scan?

[Bill Traynor (wmat)]

Done — the scaffolding is now five bullets: the ifndef:: attribute defaults, the [preface] == Document State block, the toc::[] placement, the list-of:: macros, and the [index] position.

[Kersten Richter (kersten1)]

I think this is going to need more of a walk-through. Also, it might suck, but you might put in a note saying that you or I will do it for you if you contact help@riscv - or whatever the email is.

[Bill Traynor (wmat)]

Expanded into a walk-through. It now classifies each hunk of the diff into one of two kinds — scaffolding (attributes, [preface] blocks, toc::[], list-of::, [index]), which you replicate in your own file; or an include:: line, which is the sample's chapters and you ignore — and gives a worked example of a new attribute default landing next to spec_short, with the point that spec_short stays yours.

And added the offer, as a callout at the end of the step:

If this step looks wrong to you, stop and ask rather than guessing. [...] Email help@riscv.org or open an issue on the template with template-src.diff and your src/<your-spec>.adoc attached, and someone will do this merge with you.