release: prepare v0.1.0 — steps, dependencies, and blockers (#4 and dependents)

[maehr]

Tracking issue for cutting v0.1.0, the first citable baseline. Everything below is the current state as of today, not a plan in the abstract — PR #4 has been open and green for a while, and the work that has accumulated on staging since then is what actually decides when it can go.

v0.1.0 means: the first git tag in this repo, the first GitHub Release with an attached data dump, and the first version of the standard anyone can cite. There are no tags yet in either textrefs/textrefs.org or textrefs/registry, so nothing here is a migration — it is all first-time setup.

---

1. The dependency graph

                textrefs.org                          textrefs/registry
                ------------                          -----------------
  #63  ADR-0005 preferred citation system  ──┐    #11  docs: preferred/additional systems
        └─ #67  ADR-0006 relation vocabulary ─┤    #13  ADR-0006 data reclassification
                                              │           └─ based on #11
  #71  resolver `vars` mapping ──► #72  ──────┤    #15–#19 resolver review
                                              │           └─ #20  (on #13, blocked on #72)
                    staging ◄─────────────────┘
                       │
                      #4  Release v0.1.0: staging → main
                       │
                     tag v0.1.0 → release.yml → GitHub Release + dump

#67 is stacked on #63; #13 is stacked on #11. The two repos are coupled: #67 (schema) and #13 (data) are one breaking change split across repositories.

The resolver review (#72 + #20, closing #71 and textrefs/registry#15–#19) is a second, later cross-repo pair with the same shape: #72 adds the vars resolver field to the compiler, #20 is the data that uses it. #20 is stacked on #13 and stays red until #72 reaches staging. Neither is a v0.1.0 blocker — see §4.

2. Decided: ADR-0005/0006 are in v0.1.0

This was the only real branch point, and everything else follows from it.

• Decided 2026-08-12: land feat(standard)!: preferred citation system and qualified /cite/ aliases (ADR-0005) #63 + docs(decisions): decide mapping relation vocabulary (ADR-0006) #67 first. ADR-0005 and ADR-0006 are in v0.1.0. The rest of this issue now describes one path, not two.

Rationale, as recommended and now adopted. Both are breaking changes to identifier-bearing structures, and both re-mint IRIs. Before the first tag that costs nothing — every record is draft under ADR-0004 and no identifier has ever been published. After the tag, the same change costs a documented migration against a baseline people may already cite. This is the same timing argument ADR-0006 makes for itself, applied one level up. The counter-argument — that it delays a release which is already green — was weighed and not taken.

Two consequences follow immediately: #60 (ADR-0005), #58 and #59 (ADR-0006) are now v0.1.0 issues, closed by #63 and #67 respectively; and the merge sequence in §3 is the actual plan rather than one of two options.

3. Merge sequence

The two repos guard each other, so the order is not free. There are now two coupled schema+data pairs (#67/registry#13, then #72/registry#20), and the second cannot start until the first is through:

• textrefs.org CI requires the data/ submodule pointer to be an ancestor of registry/main (.github/workflows/validate.yml).
• registry CI validates its records against textrefs.org@staging (registry/.github/workflows/validate.yml).

For a coordinated schema+data change neither side can go green first. Sequence:

• 1. Merge feat(standard)!: preferred citation system and qualified /cite/ aliases (ADR-0005) #63 (ADR-0005) → staging.
• 2. Merge docs: document preferred and additional citation systems registry#11 → registry/main.
• 3. Merge docs(decisions): decide mapping relation vocabulary (ADR-0006) #67 (ADR-0006) → staging, accepting a red data job. It is red only because the pinned submodule commit predates the change; this needs an admin merge past a check that cannot pass beforehand.
• 4. Retarget feat(works)!: reclassify mappings to alternateOf and isReferencedBy (ADR-0006) registry#13 from docs/preferred-citation-system to main, confirm it is now green against the updated staging, merge.
• 5. Bump data/ in staging to the new registry/main tip. staging is now fully green.
• 6. Rebase feat(compile): map locator variables into a provider's own vocabulary (#71) #72 onto the updated staging and merge. Its diff currently carries the feat(standard)!: preferred citation system and qualified /cite/ aliases (ADR-0005) #63/docs(decisions): decide mapping relation vocabulary (ADR-0006) #67 commits underneath it, because GitHub cannot base a cross-fork PR on another fork's branch; after steps 1–5 it collapses to the single vars commit. Its data job passes from step 5 onward.
• 7. Retarget feat(works)!: resolver review — drop non-resolving targets, add NA28/BHS/SuttaCentral/NINJAL registry#20 from feat/mapping-relation-vocabulary to main and merge. It cannot go green before step 6: registry CI validates against textrefs.org@staging, and the data uses the vars field that feat(compile): map locator variables into a provider's own vocabulary (#71) #72 introduces.
• 8. Bump data/ in staging a second time, to the registry/main tip carrying the resolver review.
• 9. Update chore(release): v0.1.0 — first citable baseline #4 — it is staging → main, so it picks all of this up automatically, but its description still describes a v0.1.0 without ADR-0005/0006 or the resolver review. Rewrite the summary, add both ADRs to the ADR list, and state the reference count the release actually ships.

All nine steps apply — going straight to #4 is off the table per §2, and steps 6–8 per §4.

4. Before tagging

• chore(release): v0.1.0 — first citable baseline #4 is BLOCKED, not failing. All four checks (CodeQL, Analyze, data, linkcheck) pass; it needs a maintainer approval to become mergeable. Confirm CODEOWNERS review is the only thing outstanding.
• CITATION.cff carries no version or date-released (CITATION.cff carries no version or date-released #51). This is a genuine release blocker: the file exists to make the release citable and currently cannot describe which release it refers to. Add both, and decide whether to reserve a Zenodo DOI now — the identifiers: block is present but commented out.
• ROADMAP.md:27 already claims the release happened: "done: Publish the Standard draft v0.1.0 as the first citable baseline (release v0.1.0)". No tag exists. Either the tag lands in this cycle or the line is wrong; also mirror any edit into src/content/docs/community/roadmap.md, per the roadmap's own maintenance rule.
• Confirm the spec version story. specification.md:9 says 0.1.0-draft, package.json says 0.1.0, and the standard pages carry maturity: working-draft. ADR-0004 and ADR-0006 both deliberately declined a spec bump under the working-draft clause. Make sure the tag v0.1.0 and the spec's 0.1.0-draft are understood as different things, and say so in the release notes.
• Regenerate CHANGELOG.md via npm run changelog (git-cliff, cliff.toml). Verify it reads sensibly for a first release — git-cliff has never run against a tag boundary here.
• Close the addressed-in-v0.1.0 issues on release: adr: review lifecycle and ephemeral draft state (retractable pre-promotion identity) #22, Upgrade to Starlight 0.41 / Astro 7 (blocked on starlight-llms-txt) #20, standard: erratum — editorial batch (RFC 9562, ld+json media type, aliases.json, tombstone rationale, namespace note) #14, standard: require canonical ASCII digit and case forms in citation-system profiles #13, standard: license and license_url both map to dcterms:license (mixed literal/IRI range) #12, standard: JSON-LD output does not emit direct SKOS mapping triples #11, standard: MappingAssertion.subject Work-IRI constraint conflicts with tombstone/versioning successor links #10, Add a complete worked example including @context #8, Dereferenceable locations: change MAY to SHOULD #7, target_kind: prefer a dereferenceable IRI + dct:conformsTo over an enumerated scheme list #6, plus adr: Introduce a preferred Citation system #60 (closed by feat(standard)!: preferred citation system and qualified /cite/ aliases (ADR-0005) #63) and standard: owl:sameAs instead of skos:exactMatch #58 and standard: replace skos:closeMatch to link to URL pages #59 (resolved together by docs(decisions): decide mapping relation vocabulary (ADR-0006) #67) now that ADR-0005/0006 are in, and feat(compile): map locator variables into a provider's own vocabulary #71 (closed by feat(compile): map locator variables into a provider's own vocabulary (#71) #72) plus data: delete resolvers that do not address the cited passage registry#15–docs: add ORCID for Luz Christopher Seiberth #19 (closed by registry#20) now that the resolver review is in.
• Label standard: owl:sameAs instead of skos:exactMatch #58, standard: replace skos:closeMatch to link to URL pages #59 and adr: Introduce a preferred Citation system #60 addressed-in-v0.1.0. They carry no labels at all today, so they do not show up in any query that drives the release checklist.
• feat: CitationSystem pages should list works instead of references #55 is already fixed on staging but its issue is still open — 03cee88 fix(site): list works instead of references on CitationSystem pages (#55) (#56). It ships in v0.1.0 whether or not anyone decides so; add it to the close-on-release list above rather than leaving it in the triage list below.
• Decided 2026-08-12: the resolver review ships in v0.1.0. feat(compile): map locator variables into a provider's own vocabulary (#71) #72 + feat(works)!: resolver review — drop non-resolving targets, add NA28/BHS/SuttaCentral/NINJAL registry#20 delete six resolver targets that do not address the cited passage, add NA28, BHS, SuttaCentral and NINJAL, and complete the New Testament (John only → 27 books) and the Tanakh (Genesis only → 39 books). So the first citable baseline covers two complete biblical corpora rather than one book of each, instead of publishing records named "New Testament" and "Tanakh" that resolve ~10% of their work. The cost is scale: the registry goes from ~39,200 references to 67,959, and with it references.jsonl to 54 MB, the built site to 204,347 pages, and npm run verify to 8m 07s locally. See §5 and §6 for what that changes.
• Last item before the release PR: publish the association's founding record. The tax authorities' decision and the foundational documents belong in the repo and on the site before v0.1.0 is tagged, as part of PR prep. The association section already carries statutes, governance, board, mission and expenses; the founding decision and constitutive documents are what make that section a record rather than a description, and the first citable baseline is the right place to freeze them.
• Triage what is deliberately not in v0.1.0. Currently open and unassigned to this release: standard: revisit locator validation mechanism (regex + examples vs. alternatives) #9 (locator validation mechanism), discussion: should TextRefs register the association in ROR (and when)? #40 / discussion: should TextRefs integrate with n2t.net / ARK (and when)? #41 (ROR, n2t/ARK discussions), feat: client-side Reference UUID generator tool #42, Mapping projection uses a denylist, so draft and deprecated mappings emit unqualified direct edges #45, Non-SPDX license values are silently dropped from the published JSON-LD #46, Draft record pages are listed in the sitemap #47, Record-page cleanup: orphaned CitationBox, duplicated draft/tombstone banner copy #48, Build-time dependency hygiene: spdx-license-ids placement, unused markdown-satteri pin #49, github-profile submodule has no consumer #50, feat: Explore WebMCP support for agent-accessible text references #52, docs: Missing whitespace around inline elements on registry pages #53, deps: upgrade to Astro 7.1 #39. Confirm each is fine to ship without. (feat: CitationSystem pages should list works instead of references #55 was in this list and has been moved above — it is already on staging.)
• Mapping projection uses a denylist, so draft and deprecated mappings emit unqualified direct edges #45 is stale, now that ADR-0006 is in — "Work SKOS projection uses a denylist" — the projection is no longer SKOS after ADR-0006, though the denylist itself (TOMBSTONE_STATUSES) is unchanged. Retitle or close.

5. Tagging and release mechanics

• Merge chore(release): v0.1.0 — first citable baseline #4 into main.
• Tag main as v0.1.0 and push the tag. This triggers .github/workflows/release.yml.
• Verify the workflow: it checks out with submodules: recursive, runs npm run build:data, and attaches dist/dump/*.jsonl + dist/dump/datapackage.json with fail_on_unmatched_files: true. This has never run. If the dump paths are wrong the release fails after the tag is already public — consider a workflow_dispatch dry run first, which the workflow already supports. With the resolver review in, that dry run matters more: npm run build:data now emits a 54 MB references.jsonl (well inside GitHub's 2 GB asset limit, but no longer a trivial upload), and the full npm run build takes ~8 minutes for 204,347 pages. Check the workflow's timeout headroom rather than assuming the previous ~3-minute build is representative.
• Confirm the pinned data/ commit at tag time is the one you want frozen into the release — main "consumes pinned SHAs at release time" per the registry workflow's comment.
• Check the generated release notes (generate_release_notes: true) against the git-cliff CHANGELOG.md; two sources of truth, decide which one leads.

6. Registry side

• The registry uses calendar tags vYYYY.MM.N and has none yet. Decide whether v0.1.0 of the standard is accompanied by a first registry export tag, or whether the dump attached to this release is sufficient for now.
• datapackage.json's SemVer-without-v version needs to be set deliberately for the first export.
• The first export ships 67,959 references across 12 works, per the §4 decision — not the ~39,200 that were in staging when this issue was opened. Set the datapackage.json version knowing that, and say the figure in the release notes: it is the most visible difference between this baseline and anything cited from an earlier snapshot.

7. Housekeeping

• Dependabot PRs target main, not staging — Build(deps): Bump fast-uri from 3.1.2 to 3.1.5 #64, Build(deps): Bump mermaid from 11.15.0 to 11.16.1 #65, Build(deps): Bump dompurify from 3.4.7 to 3.4.13 #66, Build(deps): Bump postcss from 8.5.15 to 8.5.25 #57, Build(deps): Bump sharp, @astrojs/starlight, astro, starlight-blog and starlight-llms-txt #37, Build(deps): Bump svgo from 4.0.1 to 4.0.2 #35, Build(deps): Bump @astrojs/rss from 4.0.18 to 4.0.19 #33, Build(deps): Bump the github-actions group across 1 directory with 2 updates #32, and — opened since this issue was written — Build(deps): Bump js-yaml from 4.2.0 to 4.3.1 #69 (js-yaml) and Build(deps): Bump nanoid from 3.3.12 to 3.3.18 #70 (nanoid). Since main only moves at release time, these will conflict with or be bypassed by chore(release): v0.1.0 — first citable baseline #4. Decide: retarget them to staging and fold into the release, or merge them into main after the tag. Related: deps: upgrade to Astro 7.1 #39 (Astro 7.1) and Build-time dependency hygiene: spdx-license-ids placement, unused markdown-satteri pin #49 (dependency hygiene).
• github-profile submodule has no consumer #50: the github-profile submodule has no consumer — resolve or document before the first release freezes the repo layout.
• Link Checker Report #3 is the automated Link Checker report; make sure it is clean at tag time.

---

Both open decisions are settled (2026-08-12): ADR-0005 and ADR-0006 ship in v0.1.0 (§2), and so does the resolver review (§4). Everything above is mechanical from here — the merge sequence in §3 is the critical path, and it is now nine steps across two repositories.

[maehr]

§3 merge sequence: all nine steps are through

staging is at a958928 and fully green. Both coupled schema+data pairs landed in order, and the second one is in too:

#	Step	Landed as
1	#63 ADR-0005 → staging	5c2a6f3
2	registry#11 → registry/main	7818b6b
3	#67 ADR-0006 → staging (red data, as designed)	7a94c0e
4	registry#13 retargeted to main, green, merged	0f00bd4
5	data/ bump #1	0e9c824
6	#72 rebased to one commit, merged	aba818d
7	registry#20 retargeted to main, green, merged	237e39f
8	data/ bump #2	a958928
9	Pages dispatch + this update	in progress

Both retargeted registry PRs needed a rebase rather than just a base change — their stacked bases had been squashed away — and both then went green against the updated staging exactly as §3 predicted.

Six corrections to this issue

Investigating the merge gates turned up things this issue gets wrong or misses. Recording them here because several are now fixed:

1. The main ruleset required status checks that could never report. It demanded contexts Validate and Links — workflow names. The check-runs that actually report are the job names data and linkcheck, so chore(release): v0.1.0 — first citable baseline #4 was waiting on two checks that will never arrive. Fixed: ruleset 17092029 now requires data and linkcheck; all other rules untouched. §4's "confirm CODEOWNERS review is the only thing outstanding" was also wrong — require_code_owner_review is false; what chore(release): v0.1.0 — first citable baseline #4 actually needs is 1 approval (bypassable by org admin).
2. The main ruleset also requires a successful github-pages deployment for the merged SHA, and Pages only auto-runs on push to main — the live site is deployed by dispatching Pages on staging manually. So every time staging moves, chore(release): v0.1.0 — first citable baseline #4 needs a fresh Pages dispatch or it stays blocked. Not mentioned anywhere in this issue; it is now step 9.
3. staging is unprotected. §3 step 3 called for "an admin merge past a check that cannot pass beforehand". No bypass was needed — it was a normal merge.
4. npm run changelog will not produce a 0.1.0 section. With no tags and tag_pattern = "v[0-9]*", git-cliff emits ## [Unreleased]. It needs git-cliff --tag v0.1.0. CONTRIBUTING.md:126 carries the same bug and is being fixed in the prep PR.
5. §5's build-time worry does not apply to release.yml. That workflow runs npm run build:data = compile + validate, with no astro build. The ~8 min / 204,347 pages figure belongs to validate.yml's npm run verify. Release-job timeout headroom is not a concern.
6. datapackage.json violates its own normative MUST. standard/versioning.md requires schema field descriptors per resource; writeDump (scripts/compile.ts) emits none. Decided: soften the spec text for v0.1.0 and file a follow-up for real Frictionless descriptors, rather than build them in the release critical path.

Also settled: §6's "datapackage.json's version needs to be set deliberately" needs no action — the compiler reads it from package.json, so it is already 0.1.0.

Two review findings fixed on the way through

Neither was a release blocker; both were merge-blocking conversations, and both turned out to be real:

• feat(compile): map locator variables into a provider's own vocabulary (#71) #72 — every lookup on the path to a resolver URL consulted the prototype chain. A locator value of toString resolved to Object.prototype's method and expanded into a published URL instead of skipping the entry. Locator vars are now null-prototype and all map lookups are own-property; url_by with more than one selector variable is rejected at parse time instead of silently dropping resolver targets per reference. Three new tests.
• registry#20 — John's chapter-7 verse maximum was 52, contradicting the file's own rule that entries are the highest cited verse number, not the count printed. John 7:53 opens the pericope adulterae and chapter 8 already sat at the traditional 59, so John.7.53 was unmintable. Fixed to 53.

The reference count changed

67,959, not 67,958 — the John 7:53 fix adds one. The New Testament now yields 7,954. Worth using the corrected figure in the release notes and datapackage.json discussion in §6.

[maehr]

Everything up to the tag is done

staging is at 0df2b27, #4 is MERGEABLE, and the only thing standing between here and v0.1.0 is a maintainer approval on #4. Step 9 of §3 is closed out: Pages was dispatched on staging, so a github-pages deployment exists for 0df2b27 — the exact SHA #4 merges — and #4's description has been rewritten around what the release actually ships.

Landed since the last update

PR	What
#73	All dependencies current — Astro 7.2.1, Starlight 0.41.7, and the transitive advisories behind ten dependabot PRs. Supersedes #32, #33, #35, #37, #57, #64, #65, #66, #69, #70.
#75	Release hardening: #46, #47, #49, #50.
#76	Release metadata: CITATION.cff version/date-released (closes #51), changelog, checklist fixes, versioning.md softening.

TypeScript stays on 6.x. typescript@7.0.2 is out, but astro check refuses it — the native compiler does not expose the programmatic API @astrojs/language-server needs (withastro/roadmap#1321). Verified, not assumed.

§4 triage: what was pulled in, and what stays out

Reviewing all open issues against the release (§4's last unchecked item), four were pulled in and the rest stay out deliberately:

In (#75):

• github-profile submodule has no consumer #50 — the github-profile submodule had no consumer, yet all four workflows cloned it via submodules: recursive. The tag freezes .gitmodules, so this was cheaper now than ever after.
• Draft record pages are listed in the sitemap #47 — ADR-0003 promises draft records are "noindex, excluded from sitemap and search"; only two of three shipped. v0.1.0 would have advertised 67,959 retractable URLs. The filter keys on record status, not on a route prefix, so it narrows on its own as records are promoted rather than permanently hiding pages that earned a place. Side effect worth having: the production build went from 7m47s to 3m47s at an identical 204,350 pages.
• Non-SPDX license values are silently dropped from the published JSON-LD #46 — a licence the compiler could not map to SPDX was dropped from the published record with only a console warning. Verified it fires zero times on the current registry, so this is hardening, not a data fix.
• Build-time dependency hygiene: spdx-license-ids placement, unused markdown-satteri pin #49 — spdx-license-ids is required at build time; it now sits in dependencies.

Out, and why: #74 (Frictionless descriptors — deliberately deferred, spec softened to match), #45 (mapping projection denylist — see below), #48 (component cleanup, no effect on published records), #42, #52, #9, #40, #41 (open questions and future features, none of which the tag constrains).

#45 is not obsolete. ADR-0006 renamed the relations but the denylist is unchanged — draft and deprecated assertions still project into the direct edges on Work without a status qualifier, and since ADR-0004 keeps all data at draft, every seed mapping in v0.1.0 ships that way. Retitled rather than closed.

Closed as delivered: #39 (Astro 7.1, superseded by 7.2.1), registry#16–#19 (resolver review). #58, #59, #60, #71, #55, #53 are now labelled addressed-in-v0.1.0 so they show up in the release-close query, which they did not before.

Pre-tag verification (§5)

The "this has never run" worry about release.yml is settled without touching GitHub. npm run build:data was run locally against the tagged content and emits exactly what the workflow globs, so fail_on_unmatched_files: true will not trip:

works.jsonl                4,955 B
citation-systems.jsonl     5,034 B
references.jsonl      56,228,779 B   (53.6 MB)
mappings.jsonl             9,400 B
datapackage.json           1,651 B   version "0.1.0"

validate-data reports 68,005/68,005 records valid. A workflow_dispatch dry run was deliberately not used: with no tag in the ref, action-gh-release would either fail or create a stray branch-named public release, and the local run exercises the same paths.

Zenodo is ready. Both repositories already have an active webhook on release events, so the concept DOIs mint themselves on the first release — no Zenodo UI step is outstanding. (Those hook URLs embed an access token; worth not pasting hook listings anywhere public.)

Link checker (#3) is clean — the latest links.yml runs on staging are green and the report issue has not been touched since June.

What remains

1. Publish the association's founding record — the tax authorities' decision and the foundational documents, added to §4 above as the last item before the release PR.
2. Approve and squash-merge chore(release): v0.1.0 — first citable baseline #4. It is MERGEABLE with data, linkcheck and CodeQL green and a matching github-pages deployment; reviewDecision is REVIEW_REQUIRED and the author cannot self-approve, so this needs the second maintainer or the org-admin bypass.
3. Tag and push v0.1.0 on main, then v2026.08.0 on registry/main (§6 — decided: the registry gets its own first tag and concept DOI).
4. After the release fires: fill the concept DOI into CITATION.cff and the README badge, and close the addressed-in-v0.1.0 issues.
5. Dependabot (§7): the ten npm PRs are superseded by chore(deps): refresh all dependencies before v0.1.0 #73 and can be closed rather than merged. actions/setup-node v6 → v7 (Build(deps): Bump the github-actions group across 1 directory with 2 updates #32) is the one real remaining bump; it is committed locally but needs a credential with the workflow scope to push.