Conversation
Rewrite the Get Started body around the single-identity narrative
("a passage has one identity, the editions that carry it are many"),
keeping the Keep reading and Live examples lists as deep-link entry
points.
Document the branching model in CONTRIBUTING.md: main is the
production source and auto-deploys; staging is a long-lived batching
branch for content edits; publish by squash-merging staging into main.
Manual workflow_dispatch from staging is available as an escape-hatch
preview that temporarily replaces production.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Updates the onboarding and contribution/deploy documentation to support a new long-lived staging branch workflow, while also adding an org-level .github repository as a git submodule.
Changes:
- Rewrites the Get Started page copy around the “single passage identity, many editions” narrative.
- Documents a
main(production) +staging(batching) branching/publishing model inCONTRIBUTING.md. - Adds a
github-profilesubmodule pointing attextrefs/.github.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
src/content/docs/get-started/index.md |
Reframes the Get Started explanation and adjusts link placement. |
CONTRIBUTING.md |
Adds branching/deploy workflow guidance for main/staging and PR targeting. |
.gitmodules |
Registers the new github-profile submodule for the org .github repo. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| The production site (`textrefs.org`) is built and deployed from `main`. To keep `main`'s history low-noise while still allowing many small content edits, day-to-day docs/blog/copy work batches on a long-lived `staging` branch and is squash-merged into `main` to publish. | ||
|
|
||
| - `main` — production source. Pushes here auto-deploy via `.github/workflows/pages.yml`. Release tags (`vX.Y.Z`, `vYYYY.MM.N`) are cut from `main`. |
Fixes #3. Three buckets of false-positive errors: - grep regex truncated URLs at `)`, mangling Wikipedia disambiguation titles. Allow `)` in URLs and strip only unbalanced trailing `)`. - resolver templates with `{placeholder}` reached lychee verbatim. Filter them out. - `data/package-lock.json` contributed bot-blocked opencollective URLs. Restrict grep to YAML/MD and add opencollective to lychee excludes. Also bump the registry submodule for the Perseus license_url fix, and mirror that URL change in the how-it-works example. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- npm update: astro 6.4.3 → 6.4.4 (patch) - zod 3.25.76 → 4.4.3 (was already pulled in by astro/starlight as transitive at v4; align top-level so there's one resolved copy) Zod 4 migration in schema + validator: - z.string().url() → z.url() (Iri) - z.ZodIssueCode.custom → 'custom' string literal (superRefine calls) - validate-data reportIssue path type widened to PropertyKey[] to match zod 4's $ZodIssue['path'] GH Actions are already on current majors; no bumps needed. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…ssier Vorstand minimum reduced from three to two persons (Statuten Art. 11) in DE and EN; align contributing guides to frame all three review tracks (technical, expert, board reservation) as first-class, matching the governance regulation. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
§1 previously said a conforming registry MAY record dereferenceable locations. A bare identifier with no resolution path is of limited practical use, so tighten to SHOULD to nudge implementers toward providing a resolvable URL per reference. Closes #7. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replace §13's compound JSON-shaped wrapper with a single JSON-LD document under @context + @graph. Each record carries full id, type, and administrative metadata so a reader can copy the example out and validate it directly against the published context and Zod schemas. The CanonicalReference id is the deterministic UUID v5 produced by the seed for `new-testament / bible-book-chapter-verse / John.3.16 / 1.0.0`, verified locally against standard/schema/. Closes #8. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…works Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
target_kind was an OPTIONAL human-readable scheme hint with no normative weight; maintaining Appendix B's enumerated label list was upkeep without payoff. Replace it with optional target.conforms_to — an IRI (or array of IRIs) typed as dcterms:conformsTo in the v1 JSON-LD context — mirroring Linked Art's conforms_to pattern. Spec, Appendix B, JSON-LD context, Zod schema, compile pipeline, in-tree fixture, registry detail pages, and get-started prose all migrated. The Astro mapping/work pages drop the scheme-label badge: the identifier IRI is authoritative and self-describing. The data/ submodule pointer moves to the matching textrefs/registry commit (target_kind→conforms_to in every data/works/*.yaml). See decisions/ADR-0001 for the rationale and alternatives considered. BREAKING CHANGE: target.target_kind is removed; downstream consumers that read it MUST migrate to target.conforms_to. Acceptable pre-v1.0.0. Closes #6. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
textrefs/registry#1 merged via squash; advance data/ pointer from the feature branch tip to the merge commit on main so the Validate workflow's "pin is on registry main" guard passes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Starlight reads docs/404 via getEntry() for its dedicated /404 route
AND enumerates the same entry through the [...slug] catch-all,
producing a benign but noisy build warning ("Could not render /404
from route /[...slug] as it conflicts with higher priority route
/404"). draft: true excludes the entry from the catch-all in
production builds while leaving Starlight's direct-by-id lookup
intact, so dist/404.html still ships our custom hero.
The localised dist/de/404/index.html is dropped (the fallback-route
pass uses the same draft-filtered docs list); Cloudflare Pages serves
/404.html for missing pages across all locales anyway.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* fix(ci): repair URL extraction in link-check workflow Fixes #3. Three buckets of false-positive errors: - grep regex truncated URLs at `)`, mangling Wikipedia disambiguation titles. Allow `)` in URLs and strip only unbalanced trailing `)`. - resolver templates with `{placeholder}` reached lychee verbatim. Filter them out. - `data/package-lock.json` contributed bot-blocked opencollective URLs. Restrict grep to YAML/MD and add opencollective to lychee excludes. Also bump the registry submodule for the Perseus license_url fix, and mirror that URL change in the how-it-works example. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * chore(deps): bump astro 6.4.4 and migrate to zod 4 - npm update: astro 6.4.3 → 6.4.4 (patch) - zod 3.25.76 → 4.4.3 (was already pulled in by astro/starlight as transitive at v4; align top-level so there's one resolved copy) Zod 4 migration in schema + validator: - z.string().url() → z.url() (Iri) - z.ZodIssueCode.custom → 'custom' string literal (superRefine calls) - validate-data reportIssue path type widened to PropertyKey[] to match zod 4's $ZodIssue['path'] GH Actions are already on current majors; no bumps needed. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs(association): sync statutes board size and review tracks with dossier Vorstand minimum reduced from three to two persons (Statuten Art. 11) in DE and EN; align contributing guides to frame all three review tracks (technical, expert, board reservation) as first-class, matching the governance regulation. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs(spec): tighten dereferenceable-location guidance to should (#7) §1 previously said a conforming registry MAY record dereferenceable locations. A bare identifier with no resolution path is of limited practical use, so tighten to SHOULD to nudge implementers toward providing a resolvable URL per reference. Closes #7. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs(spec): self-contained §13 example with @context (#8) Replace §13's compound JSON-shaped wrapper with a single JSON-LD document under @context + @graph. Each record carries full id, type, and administrative metadata so a reader can copy the example out and validate it directly against the published context and Zod schemas. The CanonicalReference id is the deterministic UUID v5 produced by the seed for `new-testament / bible-book-chapter-verse / John.3.16 / 1.0.0`, verified locally against standard/schema/. Closes #8. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * chore(data): bump submodule with second resolvers on single-resolver works Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * feat(spec)!: replace target_kind with dcterms:conformsTo (#6) target_kind was an OPTIONAL human-readable scheme hint with no normative weight; maintaining Appendix B's enumerated label list was upkeep without payoff. Replace it with optional target.conforms_to — an IRI (or array of IRIs) typed as dcterms:conformsTo in the v1 JSON-LD context — mirroring Linked Art's conforms_to pattern. Spec, Appendix B, JSON-LD context, Zod schema, compile pipeline, in-tree fixture, registry detail pages, and get-started prose all migrated. The Astro mapping/work pages drop the scheme-label badge: the identifier IRI is authoritative and self-describing. The data/ submodule pointer moves to the matching textrefs/registry commit (target_kind→conforms_to in every data/works/*.yaml). See decisions/ADR-0001 for the rationale and alternatives considered. BREAKING CHANGE: target.target_kind is removed; downstream consumers that read it MUST migrate to target.conforms_to. Acceptable pre-v1.0.0. Closes #6. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * chore(data): bump submodule to registry main (36cae56) textrefs/registry#1 merged via squash; advance data/ pointer from the feature branch tip to the merge commit on main so the Validate workflow's "pin is on registry main" guard passes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(404): mark docs/404.mdx as draft to drop catch-all route conflict Starlight reads docs/404 via getEntry() for its dedicated /404 route AND enumerates the same entry through the [...slug] catch-all, producing a benign but noisy build warning ("Could not render /404 from route /[...slug] as it conflicts with higher priority route /404"). draft: true excludes the entry from the catch-all in production builds while leaving Starlight's direct-by-id lookup intact, so dist/404.html still ships our custom hero. The localised dist/de/404/index.html is dropped (the fallback-route pass uses the same draft-filtered docs list); Cloudflare Pages serves /404.html for missing pages across all locales anyway. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Moritz Mähr <14755525+maehr@users.noreply.github.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
maehr
changed the title
* chore(profile): bump github-profile submodule Refresh org profile README and add a top-level README in textrefs/.github. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: add ORCID for Luz Christopher Seiberth Record ORCID 0000-0002-5606-0964 for the second author/creator in CITATION.cff and the project's Zenodo metadata, matching the existing ORCID entry for the first author. Checksum-verified valid. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Moritz Mähr <14755525+maehr@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
… tuple (ADR-0002) (#21) * feat(spec)!: seed CanonicalReference UUIDs from the semantic identity tuple Adopt ADR-0002 (fixes #15): reference UUIDs are computable offline from (work_key, citation_system_key, locator); normalization_version is removed from the data model entirely. Citation-system profiles now define canonical locator forms — non-canonical spellings are rejected at validation time, never folded — and a profile change that alters an accepted locator is a compatibility event (migration, breaking release, or new citation_system_key), not a version bump. - Zod schemas: drop normalization_version (reference + system), drop examples, add required CitationSystem.description; drop unused SemVer - compile/validate: 3-field LF-joined seed on both sides; systems emit description instead of normalization_version/examples - JSON-LD context + OpenAPI: same shape change (description = dcterms:description) - spec docs: identifier-syntax gains a purpose-of-determinism section and the canonicalization-change compatibility rule; system-profiles gains the canonical-locator-form section (relates to #13) - doc example UUIDs recomputed for the 3-field seed - data submodule → textrefs/registry#5 (systems gain description, lose normalization_version/examples) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(spec): align conformance item 6 and get-started checklist with examples removal The CitationSystem contract no longer carries examples.valid/invalid; conformance now requires description + a valid ECMAScript locator_regex. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * chore(data): bump submodule to registry review fixes (5337e71) modified bumped on all systems for the shape change; bible description aligned with its locator_regex (Copilot review on registry#5). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(spec): align quoted bible description with updated registry text Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Moritz Mähr <14755525+maehr@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
…ADR-0003) (#23) * feat(spec): add draft lifecycle with retractable pre-promotion identity Adopt ADR-0003 (fixes #22): new draft status is an ephemeral tier below candidate. The identifier-persistence promise attaches at the promotion event (draft -> candidate, expert review), not at publication. Draft records may be corrected (identity change mints a different id) or retracted (deleted, no tombstone); a re-proposed tuple regains the same UUID by construction. All records keep deterministic v5 ids at every stage - governance §6.3/6.4 no longer prescribes generated ids for provisional objects. - specification §11/§12: promotion semantics + draft status definition - identifier-syntax: immutability scoped to candidate-or-higher - versioning: ladder, draft-retraction section, promoted-must-not-cite- draft invariant (enforcement is an ADR follow-up) - governance EN/DE §4-§6: entry via technical review, promotion via expert review, tombstones scoped to promoted records - CONTRIBUTING: review tracks + flowchart - Status enum: draft added (Zod + OpenAPI) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * chore(data): bump submodule to draft-demoted registry (3f6c9f2) All records enter the ADR-0003 ladder at draft; see textrefs/registry#7. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Moritz Mähr <14755525+maehr@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
All records demoted to draft per ADR-0003 (textrefs/registry#7); pin returns to a registry main ancestor. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…profiles (#24) Fixes the spec side of #13: system profiles MUST state their leading-zero policy (default forbidden) and canonical letter case (default case-sensitive declared casing). Seed-profile examples and the worked example follow the registry: Bekker pages from 1 without leading zeros, Stephanus likewise, Bible vocabulary pinned to case-sensitive OSIS book abbreviations. Submodule bumped to registry main d31ed0b (registry#8). Co-authored-by: Moritz Mähr <14755525+maehr@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
…) (#25) - #14: RFC 9562 replaces obsoleted RFC 4122; JSON-LD siblings advertised and served as application/ld+json; alias mechanism described without the undefined aliases.json filename; undefined tombstone rationale fields dropped; UUID namespace derivation notes clarify NAMESPACE_DNS is an opaque salt. - #10 (option B): succession is provenance, not equivalence — tombstoned records carry superseded_by (dcterms:isReplacedBy); MappingAssertion stays reserved for work-level equivalence with a Work-IRI subject. New compiler invariant: superseded_by only on withdrawn/blocked records. - #11: published Work records now carry direct exactMatch/closeMatch arrays derived from accepted mappings, so skos:exactMatch/closeMatch edges exist in the JSON-LD graph alongside the reified assertions. - #12 (option 1): authored SPDX ids are emitted as canonical SPDX IRIs (https://spdx.org/licenses/{id}); dcterms:license is now IRI-typed for both license and license_url. Non-SPDX values are omitted with a compile warning (registry data already cleaned in registry#9). - data/ submodule -> registry main 2c548b3 (SPDX license cleanup). Co-authored-by: Moritz Mähr <14755525+maehr@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
…26) ADR-0003 render follow-up: /id/ record pages show a draft notice and emit robots noindex while status is draft; /reg/ listing pages inherit the flag from their work/system. The tombstone banner now follows the superseded_by successor link (was: exactMatch mapping prose) and covers blocked records. Co-authored-by: Moritz Mähr <14755525+maehr@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Moritz Mähr <14755525+maehr@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
maehr
changed the title
… latest (#29) Unblocked by starlight-llms-txt 0.11.0 (Astro 7 peers). astro 7.0.6, @astrojs/starlight 0.41.3, starlight-blog 0.27.0, starlight-openapi 0.26.0 (+ new peer @astrojs/markdown-satteri), starlight-links-validator 0.25.2, astro-mermaid 2.1.0, sharp 0.35, prettier 3.9, tsx 4.23, lint-staged 17.0.8, commitlint 21.2; lockfile regenerated. No source changes needed beyond prettier 3.9 reformatting. Co-authored-by: Moritz Mähr <14755525+maehr@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
/id/ref/{uuid}/ pages drop the Starlight chrome for a bare document
(src/layouts/RecordPage.astro) with one shared stylesheet served
unbundled at /assets/record.css: 40.7 KB -> 3.3 KB per page, site
1.9 GB -> 270 MB, back under the GitHub Pages 1 GB limit that made
staging deploys fail in syncing_files.
Content parity is kept: status tags, IRI, JSON link, draft/tombstone
banner (noindex for drafts), work/system context, Chicago citation with
COinS span for reference managers, aliases, resolver targets by
language. Dropped: copy/download citation buttons and their per-page
inline script + CSL blob (the .json sibling carries the data).
Work/system/mapping pages (46 records) keep Starlight.
Co-authored-by: Moritz Mähr <14755525+maehr@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
maehr
changed the title
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
maehr
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Release v0.1.0 — first citable baseline
Publishes staging → main as v0.1.0 (0.0.1 → 0.1.0: pre-1.0 breaking spec changes). This is the first tagged release; after merge, main is tagged
v0.1.0and a GitHub release is created from the git-cliff changelog. Community announcement with the full story: discussion #31.Standard — three ADRs adopted (
decisions/)dcterms:conformsToreplacestarget_kind(target_kind: prefer a dereferenceable IRI +dct:conformsToover an enumerated scheme list #6) — mapping targets drop the curated scheme-label column; an optionalconforms_toIRI carries the conformance claim, following Linked Art practice.CanonicalReferenceUUIDs seed from the semantic identity tuple(work_key, citation_system_key, locator)— computable offline;normalization_versionremoved from the data model (adr: purpose of deterministic UUIDs (compiler reproducibility vs. offline minting) #15).draftlifecycle tier belowcandidate. The identifier-persistence promise attaches at promotion (expert review), not publication. Drafts may be corrected or retracted without tombstones (adr: review lifecycle and ephemeral draft state (retractable pre-promotion identity) #22).Standard — further changes
@context(Add a complete worked example including@context#8).superseded_by(dcterms:isReplacedBy);MappingAssertionreserved for work-level equivalence (standard: MappingAssertion.subject Work-IRI constraint conflicts with tombstone/versioning successor links #10).skos:exactMatch/skos:closeMatchedges emitted on published works (standard: JSON-LD output does not emit direct SKOS mapping triples #11).dcterms:licensenow single IRI-typed range; SPDX ids emitted as canonical SPDX IRIs (standard: license and license_url both map to dcterms:license (mixed literal/IRI range) #12).application/ld+json, alias-mechanism prose, namespace-salt notes (standard: erratum — editorial batch (RFC 9562, ld+json media type, aliases.json, tombstone rationale, namespace note) #14).Registry data (submodule → textrefs/registry)
draft(registry#7): TextRefs is pre-stable; no identifier carries a persistence promise until expert review promotes it. One-time bootstrap demotion — the ladder is one-way from here.descriptionrequired;examples/normalization_versiondropped (registry#5).Site, CI, governance
starlight-llms-txt@0.11.0; zero source changes needed.noindexed on/id/and/reg/pages (feat(site): draft records flagged + noindexed (ADR-0003 follow-up) #26).Review
This PR is the agreed community-review venue for the three ADRs in
decisions/. @julsraemy — your three issues are resolved here (#6 via ADR-0001, #7 SHOULD, #8 worked example); a review of the ADRs would be very welcome.Closes #6. Closes #7. Closes #8. Closes #10. Closes #11. Closes #12. Closes #13. Closes #14. Closes #15. Closes #20. Closes #22.
🤖 Generated with Claude Code