Skip to content

0006 — Ship the proposition reorganization as 1.1.0, in place under /v1/

  • Status: Accepted
  • Date: 2026-10-18
  • Spec (if any): docs/superpowers/plans/2026-10-18-proposition-reorganization.md (plan PR #155)
  • Amended: 2026-10-20 by ADR 0009 (R2 layout mirrors NCBI ClinVar, PR #168): Decision 2's "in place under /v1/" becomes the new line folder v1/1.1/, and the 1.0.1 generation becomes the frozen line v1/1.0/. Decisions 1, 3 and 4 stand.
  • Amended: 2026-10-21 by ADR 0008 and ADR 0009 (PR #168): the maintainer declared 1.1.0 GA. The initial-stabilization exception ends with 1.1.0; published files are immutable from 1.1.0, and a later breaking change opens v2/. A superseded line is frozen and kept indefinitely (no EOL date, no deprecation window), and a content-only correction that rewrites bundles opens a new MINOR line folder. 1.1.0 used a completion notice only (ADR 0008 (g)).

Context

The next release was being prepared as 1.0.2: a schema-conformance fix to ClinvarCategoricalVariant (#142) plus corrective data and Parquet fixes, delivered through a patch-style backfill of the published releases.

On 2026-10-18 the proposition reorganization was added to the same release. The four proposition sections and Parquet tables, grouped by object shape (varcond-, varcustom-, vartumor-, vartherapy-proposition), become four grouped by meaning (propositionPathogenicity, propositionOncogenicity, propositionSomaticClinicalImpact, propositionClinvarCustom). The Parquet tables share one column schema, which renames some columns. Every statement and evidence-line pointer changes, so the patch backfill no longer fits. The release becomes one full rebuild of all 16 datasets, with every published bundle and Parquet set re-assembled and re-exported.

ADR 0004 gives three ways to label this:

  • §1: a PATCH must not change valid instances. Renaming sections and tables does, so 1.0.2 is wrong.
  • §3/§4: a breaking change after GA gets a new MAJOR line (/v2/) and the prior line stays live for 6 months, after a 4-week RFC (§8).
  • §5: until GA, the 1.x line may take breaking changes in place, announced rather than RFC'd. §5 names corrective fixes. The reorganization is a deliberate redesign, not a correction.

Decision

  1. Ship the proposition reorganization and the pending fixes as 1.1.0: the schema $ids (w3id.org/clingen/schema/clinvar-gkm/1.1.0/…), the bundle schema_version const and the assembler's SCHEMA_VERSION.
  2. Publish it in place under /v1/, under the §5 stabilization exception. ADR 0004 §4 keys directories by MAJOR, so a MINOR stays in /v1/. All 4 monthly fulls, 00-latest, the 15 weekly deltas and every Parquet set are rewritten, and the old var*-proposition files are removed.
  3. No new MAJOR line, no parallel line, and no 1.0.2 tag. The release is one tag, 1.1.0, on the 1.0 release branch. The branch keeps its name, since it carries the 1.x line.
  4. This ADR extends §5 to cover a deliberate structural change made before GA, not only corrective fixes. After GA, the full MAJOR, parallel-line and RFC process governs every breaking change, as ADR 0004 says.

Rationale

  • Not a PATCH. Under §1 a PATCH changes no valid instance. This release renames sections, Parquet tables and columns, and rewrites every pointer, so 1.0.2 would mislabel it.
  • A MINOR is the most honest label that stays in /v1/. It is not strict semver, since a MINOR should be additive. But a consumer that pins a 1.0.x $id gets a clear signal that something changed, and the R2 layout stays put.
  • A new MAJOR costs more than it protects. /v2/ would double the pipeline and storage for 6 months and add a 4-week RFC. Before GA there are few consumers, so the parallel line would protect almost no one.
  • One rebuild. Labelling the fixes and the redesign together means one rebuild and one republish, not two.

Consequences

  • Announcements (ADR 0004 §6, §7). These are required, in this order:
  • An advance notice with the cutover date, posted before any R2 overwrite.
  • A completion notice after the republish is verified.

Both go to GitHub Discussions Announcements, the v1/feed.xml Atom feed, the GitHub Release notes and the Changelog. The Google Group clinvar-gkm@broadinstitute.org went live on 2026-10-18 (#167). Today generate-r2-index.sh builds the feed from the R2 listing alone (one entry per file, no summary text), so the republish re-dates every entry but cannot carry the notice text. A notice entry in the feed is a generator follow-up. Both notices cover the old → new section and table mapping, the column renames, the 1.1.0 $ids and schema_version, the corrective fixes in the same release, and the fact that every published file is rewritten in place, so checksums change and earlier downloads should be refreshed. - Version strings. Every 1.0.2 string on the open 1.0 PRs (#142, #145, #153 and the rest) is relabelled 1.1.0 before they merge. Gate before tagging: grep -r 1.0.2 schema src returns nothing. - Tagging. Tagging 1.1.0 makes the new w3id $ids resolve through the existing dynamic rule (no .htaccess change). The 1.0.0 and 1.0.1 tags and their $ids stay resolvable. - Local copies. Copies downloaded before 1.1.0 keep the old sections and tables. The plan's migration notes show how to rebuild the new shape from their data column. - Precedent. The extension in Decision 4 ends at GA. Once GA is declared, a change like this needs a /v2/ line and an RFC.