Corpus versioning
Status: proposed
The corpus is versioned as a whole with semantic versioning. main carries the next version with a -dev suffix; the first is 0.1.0-dev. A project validates against one release and stays on it until it adopts a later release and validates again.
A breaking change is any of the following: - an IRI is removed or renamed; - a constraint is tightened so that conforming records fail; - a notation used by a workflow or an instrument mapping changes; - a derivation rule, rate definition or parameter default changes; - an approved entry that records use is withdrawn.
Additions and loosenings are additive. Wording that changes no constraint is editorial. While the version is 0.x, a breaking change takes a minor version; from 1.0.0 it takes a major version. Additions take a minor version and editorial changes a patch.
A release fixes the bytes of every artifact through a manifest and its digest. The release procedure is greeningstandard ADR-0024’s:
| Version | Use |
|---|---|
X.Y.Z-dev |
Unfinished work on main; nothing pins it |
X.Y.Z-pilot.N |
A frozen, tagged pre-release; a project in pilot pins it |
X.Y.Z |
A frozen, tagged full release; production pins it |
The version is stamped in the ontology’s owl:versionInfo, the catalog’s current distribution and the release manifest (dataRequirements/releases/X.Y.Z/release-manifest.jsonld). A cut writes a sha256 for every artifact into the manifest; the manifest’s own sha256 is the release digest, and a consumer pins the version and the digest together. A full release promotes a pilot with version changes only: any content change needs another pilot. Only the standard author promotes. A cut is tagged only after the gate (check-standard.sh) has passed on that exact commit, and the person cutting pushes. tooling/cut_release.py, tooling/verify_release.py and tooling/gate-at-commit.sh implement it; the release procedure says how.
NWSS differs from ADR-0024 in four ways. It has no instrument mappings or project design form yet, so nothing but the ontology, catalog and manifest carries the version. The fixture ledger under tests/fixtures/ledger/ is a release artifact, listed by globbing it at each cut, so the manifest names exactly the fixtures the cut commit holds. It has no releases from before the procedure, so every artifact of every cut carries a checksum. And main takes changes only through pull requests, so a cut starts on main and commits to a branch release-<version>; the tag and the return to -dev are made there, and the branch is merged with a merge commit so the tagged commit stays in main’s history.
Mirrors ncgs ADR-0017 and ADR-0024.