AGENTS.md:219 and CONTRIBUTING.md:52 both ask contributors to cite the spec version alongside a behavioural claim — "describe behavior and spec version (e.g. spec v0.88.0)" — but neither says which version to name. Read literally, the pinned version satisfies the instruction, and that reading produces a marker that goes stale on every substrait-packaging bump while the rule it annotates never moves. The intended reading is the version that introduced or changed the behaviour, so the marker stays true for the life of the comment.
The convention is followed correctly everywhere it currently appears on main, so this is a gap in the instructions rather than a drift in the code. Each of the six markers names the release that actually changed the rule:
| marker |
the spec change it names |
FunctionBindingResolver:526, ParameterizedType:451, TypeExpressionEvaluator:34, AggregateConversion:42 — v0.99.0 |
5153493 feat: add unbound type for partially bound plans (#1081), the only spec change in v0.98.0..v0.99.0 |
ParseToPojo:236 — v0.92.1 |
254a482 fix(grammar): align type expressions with extension YAML (#1082) |
TestTypeParser:80 — v0.95.0 |
d4eee3d fix(grammar)!: give binary operators conventional precedence (#1107) |
The ambiguity is not hypothetical: #1161 added two markers reading (spec v0.101.0) on the rule that an aggregate's grouping columns are ordered by the relation's shared grouping-expression list. That rule arrived in substrait-io/substrait#706, released in v0.57.0, and the Direct Output Order sentence in site/docs/relations/logical_relations.md is byte-identical from that tag through v0.101.0 — v0.101.0 is simply what this repo pins. Both markers are being dropped in review.
Worth stating in the same edit: a long-standing invariant needs no marker at all. Correcting a case like the one above to v0.57.0 would be accurate but still noise, since nobody is tracking a rule that has held for two years — the marker earns its place only when a reader might otherwise assume the older behaviour.
Sites to update: AGENTS.md:207, AGENTS.md:219, CONTRIBUTING.md:52.
AGENTS.md:219andCONTRIBUTING.md:52both ask contributors to cite the spec version alongside a behavioural claim — "describe behavior and spec version (e.g.spec v0.88.0)" — but neither says which version to name. Read literally, the pinned version satisfies the instruction, and that reading produces a marker that goes stale on everysubstrait-packagingbump while the rule it annotates never moves. The intended reading is the version that introduced or changed the behaviour, so the marker stays true for the life of the comment.The convention is followed correctly everywhere it currently appears on
main, so this is a gap in the instructions rather than a drift in the code. Each of the six markers names the release that actually changed the rule:FunctionBindingResolver:526,ParameterizedType:451,TypeExpressionEvaluator:34,AggregateConversion:42—v0.99.05153493 feat: add unbound type for partially bound plans (#1081), the only spec change inv0.98.0..v0.99.0ParseToPojo:236—v0.92.1254a482 fix(grammar): align type expressions with extension YAML (#1082)TestTypeParser:80—v0.95.0d4eee3d fix(grammar)!: give binary operators conventional precedence (#1107)The ambiguity is not hypothetical: #1161 added two markers reading
(spec v0.101.0)on the rule that an aggregate's grouping columns are ordered by the relation's shared grouping-expression list. That rule arrived in substrait-io/substrait#706, released in v0.57.0, and the Direct Output Order sentence insite/docs/relations/logical_relations.mdis byte-identical from that tag through v0.101.0 —v0.101.0is simply what this repo pins. Both markers are being dropped in review.Worth stating in the same edit: a long-standing invariant needs no marker at all. Correcting a case like the one above to
v0.57.0would be accurate but still noise, since nobody is tracking a rule that has held for two years — the marker earns its place only when a reader might otherwise assume the older behaviour.Sites to update:
AGENTS.md:207,AGENTS.md:219,CONTRIBUTING.md:52.