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`. |
|
|
||
| ## Branching model | ||
|
|
||
| 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. |
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
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.
Summary
Squash-merge candidate for shipping everything that has accumulated on
stagingsince the lastmaincut. Single bundle, one production deploy.Spec (closes #6, #7, #8)
docs(spec): tighten dereferenceable-location guidance to should. §1 MAY → SHOULD for recording dereferenceable locations.@context#8 —docs(spec): self-contained §13 example with @context. §13 worked example rewritten as one JSON-LD document under@context+@graph, with fullid,type, and admin metadata on each record. Validated against the canonical Zod schemas.target_kind: prefer a dereferenceable IRI +dct:conformsToover an enumerated scheme list #6 —feat(spec)!: replace target_kind with dcterms:conformsTo. Retire the informativetarget_kindhint and Appendix B's enumerated label list. Introduce optionaltarget.conforms_to(IRI or array of IRIs) mapped todcterms:conformsToin the v1 JSON-LD context. Spec, Appendix B, JSON-LD context, Zod schema, compile pipeline, in-tree fixture, registry detail pages, and get-started prose all migrated; coordinated with fix(perseus): replace dead license_url with /hopper/opensource registry#1 which renames the field across everydata/works/*.yaml. Rationale indecisions/ADR-0001-conforms-to-replaces-target-kind.md(first ADR in the repo).CI / dependencies (closes #3)
fix(ci): link-check workflow false positives. URL extraction was truncating at), feeding{placeholder}resolver templates to lychee, and scanningdata/package-lock.json(bot-blocked opencollective URLs). Allow)in URLs with an unbalanced-paren trim, drop{}-bearing URLs, restrict grep to YAML/MD, add opencollective to lychee excludes. Local replay drops error count 17 → 0.chore(deps): astro 6.4.3 → 6.4.4 (patch), zod 3 → 4.4.3 (top-level aligned with the v4 already pulled in transitively by astro/starlight). Migratedz.string().url()→z.url(),z.ZodIssueCode.custom→'custom', widenedreportIssuepath type toPropertyKey[]for zod 4's$ZodIssue.fix(404):src/content/docs/404.mdxnowdraft: true. Silences theCould not render /404 from route /[...slug] as it conflicts with higher priority route /404build warning. Starlight still resolves the entry by id for/404.html; the German fallback at/de/404/is dropped (Cloudflare Pages serves/404.htmlfor missing pages across locales).Data / submodule
chore(data):data/submodule advances to36cae56onregistry/main, picking up the Perseuslicense_urlfix (/hopper/about/copyright→/hopper/opensource), second resolvers on previously single-resolver works, and the registry-sidetarget_kind→conforms_torename.Content / governance
docs: revise get-started prose and document staging deploy flow. Get Started body rewritten around the single-identity narrative;CONTRIBUTING.mddocuments themain/stagingbranching model used by this PR.docs(association): sync statutes board size and review tracks with dossier. Vorstand minimum reduced from three to two (Statuten Art. 11) in DE and EN; align contributing guides to frame all three review tracks (technical, expert, board reservation) as first-class.chore: add textrefs/.github as submodule at github-profile/.Test plan
npm run verify— 0 errors / 0 warnings / 0 hints (locally).npm run build:data— 39250/39250 records validate against the new schema and migrated registry (locally).npm run build:fast— 87 pages, internal links valid,/404warning gone.staging:data✓,linkcheck✓.main; spot-check/standard/specification/§1/§10/§13/Appendix B, the rendered/404, and at least one/id/mapping/{uuid}/page.Closes #3. Closes #6. Closes #7. Closes #8.
🤖 Generated with Claude Code