Skip to content

docs: record that the stable app ships 0.x libraries of a draft ecosystem - #94

Merged
ixuz merged 1 commit into
mainfrom
dependency-maturity-decision
Oct 15, 2026
Merged

ixuz merged 1 commit into
mainfrom
dependency-maturity-decision

Conversation

@ixuz

@ixuz ixuz commented Oct 15, 2026

Copy link
Copy Markdown
Contributor

What and why

Criterion 16 of the Standard for Public Code says that a version ready to use depends only on versions ready to use. Every version from 1.0.0 on is declared ready, and each one ships four dependencies before their own 1.0.0. vendor-code.md gives each of them a reason. But nothing recorded the project's choice to ship a stable app on a pre-1.0 ecosystem. The assessment also listed the MUST as partial with no path, as if it were work waiting to be done.

This pull request records that choice and makes the docs say the same:

  • Decision 14 in the assessment's "Decisions made": Solid Memo is stable within an ecosystem that is not yet at 1.0. The Solid Protocol and Solid-OIDC are drafts, and the libraries around them are 0.x. The four allowed dependencies stay, each with its reason. Criterion 16's MUST is a recorded gap until they reach 1.0.0 or a replacement ready to use exists. A new dependency before 1.0.0 is still refused unless it is added with its reason.
  • The assessment: criterion 16's MUST stays partial and names decision 14. "Gaps that remain" calls it a decided gap and says what closes it. The summary says so too. The score stays 40/46.
  • vendor-code.md#maturity: one sentence before the table points to decision 14. Each row now says what that package's 0.x means, with its source:
  • The wording: ALLOWED in scripts/checkDependencies.ts, vendor-code.md and the assessment no longer say that rdf-validate-shacl is "the only SHACL engine for RDF/JS" or "has no replacement". shacl-engine 1.x exists, but it brings in packages before 1.0.0 of its own (rdf-validation 0.1, process 0.11) and a SPARQL engine the app does not need.

npm run check:dependencies is unchanged: it still allows only these four. defunctzombie is added to the cspell words for the link.

Refs: #89

Checklist

  • One issue. This pull request addresses one issue, linked above.
  • Done, as AGENTS.md defines it: npm run check passes (lint, Markdown and spelling included), npm run lint:reuse too if a file was added, and npm run crosscheck too if ns/ or decks/ changed. (lint:reuse and crosscheck n/a: no file was added, and ns/ and decks/ are unchanged)
  • Tests. New and changed code has its tests, and every package stays at 100% coverage (docs/testing.md). (n/a: only the reason strings in ALLOWED changed, and the existing tests cover them)
  • Docs. The docs say what changed, and a new page in docs/ is listed in docs/README.md.
  • Languages. A new or changed message is in every locale: en, sv, ko, de, es and fr (packages/ui/src/i18n/). (n/a: no UI message changed)
  • Vocabulary and shapes. Any change to ns/ was agreed in an issue first; no published ns/shapes/*/vN.ttl or decks/*/vN.ttl was edited; generated files were regenerated, not edited. (n/a: ns/ and decks/ are unchanged)
  • Breaking? Nothing in the public API breaks, or a commit says so (! and a BREAKING CHANGE: footer). npm run check:breaking sees a line of api/ that goes, but not a feature removed, nor a reader that reads less than before.
  • Pod data. Any change to what the app writes to a pod comes with its migration (docs/migrations.md). (n/a: nothing written to a pod changed)
  • Policy. Any change to an external rule the code follows (SM-2, the plural rules, a specification) is cited. (Criterion 16 of the Standard for Public Code, and each package's tracker for what its 0.x means)
  • Licenses. New content is MIT, or a deck states its own license; a new file has its SPDX header (npm run lint:reuse), or a new deck its line in REUSE.toml; third-party content is credited. (n/a: no file was added)
  • Architecture. Imports follow docs/boundaries.md and the layers of docs/architecture.md. (n/a: no import changed)
  • Run. I ran the app (npm run dev) and tried the change, and considered the user journeys. (n/a: only docs and the reason strings of a check script changed; the app is unchanged)
  • Commits. Each commit is one logical change, in Conventional Commits form (type(scope): subject, ! and a BREAKING CHANGE: footer if it breaks something), with an imperative subject and a body that explains why (CONTRIBUTING.md).

…stem

Criterion 16 of the Standard for Public Code asks that a version ready
to use depends only on versions ready to use. Every version from 1.0.0
on is declared ready, and it ships four dependencies before their own
1.0.0. vendor-code.md gave each one a reason, but nothing recorded the
project's choice to ship a stable app on them, and the assessment
listed the MUST as partial with no path, as if it were work waiting.

Decision 14 records it: Solid Memo is stable within an ecosystem that
is not yet at 1.0, the four stay with their reasons, and the MUST is a
gap until they reach 1.0.0 or a ready replacement exists. Criterion
16, "Gaps that remain" and vendor-code.md point to it. Each row of
vendor-code.md now says what that package's 0.x means: process is
final at 0.11 by its maintainer's choice, and the two Zazuko packages
break only in a 0.x minor, which a caret range keeps out, so the risk
is slow upkeep.

ALLOWED, vendor-code.md and the assessment called rdf-validate-shacl
the only SHACL engine for RDF/JS, with no replacement. shacl-engine
has been at 1.0.0 since 2024, but brings in packages before 1.0.0 of
its own and a SPARQL engine the app does not need, so they now say so.

Closes: #89
@ixuz ixuz added documentation Improvements or additions to documentation dependencies Dependency versions, pins and updates labels Oct 15, 2026
@ixuz
ixuz added this pull request to the merge queue Oct 15, 2026
Merged via the queue into main with commit aff39fe Oct 15, 2026
16 checks passed
@ixuz
ixuz deleted the dependency-maturity-decision branch October 16, 2026 14:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dependencies Dependency versions, pins and updates documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant