Pin catalog components by major

Andrew Dunnrequested to merge
pin-major into main

Standard

pipeline

Change type

  • Modify existing standard (prose only)
  • Modify existing standard's check.sh (change an assertion)
  • Modify existing standard's templates

What does this MR do and why?

Catalog component pins become the major, @6, instead of a full @vX.Y.Z tag, so a patch to a component reaches its consumers without an edit in each one. Minors and patches resolve to the newest matching catalog release at pipeline time; a major bump stays the deliberate edit, read against the catalog CHANGELOG's breaking section. The pipeline standard asks for the major rather than tolerating it, and a full pin still passes for migration.

Carried with it, because the pins cannot land without them: CATALOG-VERSION holds 6, just sync and just validate read and write @6 and match either pin shape, and the paper template's @~latest becomes @6. reference_version stays full semver, since the reference is not a catalog resource.

Failure mode this addresses

check.sh:16 asserted @v?[0-9]+\.[0-9]+\.[0-9]+, so @6 failed just check-one STANDARD=pipeline while resolving correctly on the platform. The same assertion accepted @6.2.2, and SKILL.md said "Both @v1.5.0 and @1.5.0 are accepted". That form has never resolved: a partial is resolved as a range over release versions, a three-part version as a literal tag, and this catalog's tags are named vX.Y.Z. The standard was passing a pin whose pipeline cannot start.

Assertion deltas

  • MODIFY: file-contains:.gitlab-ci.yml, from @v?[0-9]+\.[0-9]+\.[0-9]+ to @(v[0-9]+\.[0-9]+\.[0-9]+|[0-9]+(\.[0-9]+)?)([^0-9.]|$)

The alternation is the resolver's own grammar, verified against the live catalog with POST /projects/:id/ci/lint on pipeline/vale: @6, @6.2, @v6.2.2 and @~latest resolve, while @6.2.2, @v6 and @v6.2 return content not found. The trailing boundary is load bearing, because grep -E matches a substring and the partial branch otherwise matches the 6.2 in @6.2.2.

Consumer impact

A full @vX.Y.Z pin keeps passing, and @6 passes where it previously failed. @6.2.2, @v6 and @v6.2 now fail, and those includes do not resolve today either. Consumers move their own pins to @6 in a separate sweep.

Test plan

  • just guard passes (assertions use only closed primitives)
  • just check-one STANDARD=pipeline passes against this repo
  • Four fixtures, two negative: @6 and @v6.2.2 pass 5/0; @v6, @6.2.2 fail 4/1
  • just validate and just check green, 21 standards pass and 0 fail
  • CHANGELOG updated

Merge request reports