Skip to content

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

Open

Description

@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.


0. Where this stands (2026-09-03)

Content is complete. Two mechanical steps remain, and both are maintainer
actions.

Sections 1 to 3 are done, every content item in §4 is ticked, and staging is at
ba908c7. #4 is MERGEABLE with all four checks passing (CodeQL, Analyze,
data, linkcheck); it is BLOCKED on one maintainer approval, nothing else. The
full npm run verify is green against the real registry: 0 astro check errors,
137/137 tests, 259,813 pages, all internal links valid.

What is left, in order:

  1. Dispatch github-pages on ba908c7. The ruleset requires a deployment
    for the SHA being merged, and Pages only auto-runs on push to main. The last
    dispatch was 56cab1b on 2026-08-31, now eleven commits stale. Nothing
    further is queued for staging, so this is the last action before approval;
    if staging moves again, repeat it on the new tip. See §5.
  2. Approve and merge chore(release): v0.1.0 — first citable baseline #4, then tag, then verify the release workflow. See §5,
    and do the workflow_dispatch dry run first — release.yml has still never
    run and references.jsonl is now 69 MB.

What landed since the 2026-08-27 revision of this section, in eleven commits:

On closing issues. The rule stated in item 1 of the old list — label rather
than close, because Closes does not fire from a merge into staging — has been
replaced in practice: an issue is now closed by hand as soon as its fix reaches
staging, with a comment naming the commit. No issue carries
addressed-in-v0.1.0 any more.

Everything else in this issue is history. The decisions in §2 and §4 are settled
and are not reopened here.


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.

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:

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

4. Before tagging

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.

  • Do the workflow_dispatch dry run of release.yml before tagging. It checks out with submodules: recursive, runs npm run build:data, and attaches dist/dump/*.jsonl + dist/dump/datapackage.json + aliases.json with fail_on_unmatched_files: true. It has still never run. If a dump path is wrong the release fails after the tag is already public.

    The payload has grown twice since this line was written. Measured on a5764fb (2026-08-27) with the full npm run verify:

    When this issue was opened After the resolver review Now
    References ~39,200 67,959 86,397
    references.jsonl — 54 MB 69 MB (72,591,804 bytes)
    aliases.json — 12.9 MB 17 MB (17,521,319 bytes)
    Pages built — 204,347 259,811

    Still far inside GitHub's 2 GB asset limit, but check the workflow's timeout headroom against the current build rather than the old one.

  • Confirm the three ADR links resolve. identifier-syntax.md, mappings-and-resolver-targets.md and related-systems.md link to ADR-0001, ADR-0002 and ADR-0006 at blob/main/decisions/…. main carries only ADR-TEMPLATE.md and README.md today, so all three 404 and are the only real errors left in Link Checker Report #3. Merging chore(release): v0.1.0 — first citable baseline #4 brings all seven ADRs to main and resolves them. Re-run the Links workflow after the tag to confirm.

  • 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 86,397 references across 23 works and 13 citation systems — 86,477 records and 172,838 aliases — not the ~39,200 in staging when this issue was opened, and not the 67,959 the §4 decision produced. chore(data): bump the registry pointer to 455bb27f #95 and chore(data): bump the registry pointer to 7d109195 #96 advanced the data/ pin to 7d10919 afterwards, adding Dante's Divina Commedia, Hume's Treatise and first Enquiry, and eight Nietzsche works. Say the current figure in the release notes — it is the most visible difference between this baseline and anything cited from an earlier snapshot, and the earlier figure is now wrong in two places rather than one. datapackage.json is at version 0.1.0.

7. Housekeeping


Every decision is settled. ADR-0005 and ADR-0006 ship in v0.1.0 (§2, 2026-08-12), so does the resolver review (§4, 2026-08-12), and the deprecated rendering question is answered (§4, 2026-08-27). The merge sequence in §3 is through. What is left is §0: land #101, publish the founding record, dispatch Pages, approve and merge #4, tag, and close out.

Activity

  1. maehr commented on Aug 12, 2026

    @maehr
    MemberAuthor

    §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.

  2. maehr commented on Aug 12, 2026

    @maehr
    MemberAuthor

    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):

    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.
  3. maehr commented on Aug 13, 2026

    @maehr
    MemberAuthor

    The documentation wave is in: staging is at 3f6670e

    #80 is squash-merged. It resolves 40 of the 41 findings in #79 and all of #81, and it is the last content change planned before the tag.

    This issue predates both, so the pre-tag picture has moved:

    Since the last update
    #77 actions/setup-node v6 → v7 — closes the one real remaining dependabot bump from §7 (#32)
    #78 Dependabot version updates now target staging, so the ten superseded PRs stop reopening the §7 question
    #80 Documentation consistency audit (#79) and related standards (#81)

    Why the docs changed before the tag rather than after

    Four of the audit findings would otherwise have frozen wrong statements into a citable baseline: §13's flagship Work example was invalid against Work.safeParse for want of preferred_citation_system_key (ADR-0005), the OpenAPI document advertised application/json where the implementation emits application/ld+json and omitted Work.creators entirely, and §14 required BCP 47 validation that all three schema layers implemented as minLength: 2. The last one is now a real shared LanguageTag, mirrored into the OpenAPI pattern; all 12 registry language values still validate.

    Two findings were also publishing the wrong branching model — the contributing page told contributors to branch from and PR against main, which is exactly the workflow this release does not use.

    #81 reframed the related-systems page around the layer each standard addresses and added IIIF, W3C Web Annotation, BIBFRAME, IFLA LRM and RAMEN, plus URN:NBN — which Appendix B of the spec already listed and that page did not.

    Consequence for #4, and it is a blocking one

    staging has moved three times since #4's description was rewritten. Per correction 2 in my earlier comment, the main ruleset requires a successful github-pages deployment for the SHA being merged, and Pages only auto-runs on push to main:

    latest github-pages deployment   37faf37   2026-08-12T21:47Z
    staging tip                      3f6670e   now
    

    So #4 needs a fresh Pages dispatch on staging at 3f6670e before it can merge. data and linkcheck are re-running against the new tip on their own; the deployment is the one that will not appear by itself. This is the step that has to be repeated every single time staging moves, and it is worth doing last, immediately before the approval.

    §4 checklist

    Corrections to the earlier updates

    1. npm test count moved. Earlier comments and chore(release): v0.1.0 — first citable baseline #4's description cite 25 tests; docs: resolve the consistency audit before v0.1.0 (#79) #80 added the resolver-language and grandfathered-tag cases, so it is 30/30 now. Nothing else in the verification block changed.
    2. The reference count did not move. 67,959 across 12 works, 68,005 records. docs: resolve the consistency audit before v0.1.0 (#79) #80 touched no registry data and the data/ pin is still textrefs/registry@237e39f.

    What remains, unchanged from the last update

    1. Publish the association's founding record.
    2. Dispatch Pages on staging at the final SHA.
    3. Approve and squash-merge chore(release): v0.1.0 — first citable baseline #4 — reviewDecision is still REVIEW_REQUIRED and the author cannot self-approve.
    4. Tag v0.1.0 on main, then v2026.08.0 on registry/main.
    5. After the release fires: fill the concept DOI into CITATION.cff and the README badge, and close the addressed-in-v0.1.0 issues — docs: add more systems like IIIF #81 joins that list.
  4. maehr commented on Sep 2, 2026

    @maehr
    MemberAuthor

    Open-issue reconciliation on 2026-09-02:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions