Left open by #13. Issue #9 supplied no answer.
specifications/listing/v1/spec.md §4:
TODO — category and lifecycleStage are controlled vocabularies. State the governance rule for adding a term — this is the field most likely to need extension, and unmanaged growth makes the storefront incoherent. Note that adding a term is a minor release and removing one is major, since narrowing an enum rejects a document that validated before.
Why it matters
The TODO has already worked out the compatibility mechanics: adding a term is minor, removing one is major. What is missing is the editorial rule, and that is the part that decays.
category is the field a publisher reaches for when none of the existing terms fit, and the path of least resistance is always to add one. Twenty categories is a taxonomy; sixty is a list, and a storefront with sixty categories has none. Nothing in GOVERNANCE.md distinguishes "add an optional field" — an ordinary change needing one approval — from "add a category", which is a product decision with no technical cost and a real editorial one.
The concrete questions
- Who decides, and against what test? A new term should have to justify itself against the terms that already exist.
- Is there a ceiling, or a rule that adding one term obliges merging two?
lifecycleStage is a different animal and probably should not share the answer. It is a small closed progression, not an open taxonomy, and a new stage changes what the storefront means rather than how it sorts.- Does the rule belong in GOVERNANCE.md rather than in
spec.md? It is a process rule, and GOVERNANCE.md is where the other process rules live.
What deciding it costs
Nothing technical — no schema change, no new diagnostic. It is prose, plus most likely a short section in GOVERNANCE.md. The cost of not deciding it is paid slowly and is not recoverable, since removing a term is a major version.
Refs #9
Left open by #13. Issue #9 supplied no answer.
specifications/listing/v1/spec.md§4:Why it matters
The TODO has already worked out the compatibility mechanics: adding a term is minor, removing one is major. What is missing is the editorial rule, and that is the part that decays.
categoryis the field a publisher reaches for when none of the existing terms fit, and the path of least resistance is always to add one. Twenty categories is a taxonomy; sixty is a list, and a storefront with sixty categories has none. Nothing in GOVERNANCE.md distinguishes "add an optional field" — an ordinary change needing one approval — from "add a category", which is a product decision with no technical cost and a real editorial one.The concrete questions
lifecycleStageis a different animal and probably should not share the answer. It is a small closed progression, not an open taxonomy, and a new stage changes what the storefront means rather than how it sorts.spec.md? It is a process rule, and GOVERNANCE.md is where the other process rules live.What deciding it costs
Nothing technical — no schema change, no new diagnostic. It is prose, plus most likely a short section in GOVERNANCE.md. The cost of not deciding it is paid slowly and is not recoverable, since removing a term is a major version.
Refs #9