B-RY9T-milestone-order-has-two-sources-version-and-the-vision-phase
D-0002-entity-identifier-shape is explicit that order lives outside the
id: milestones order by version, and ascending semver is the roadmap. The
generated index follows it. milestoneOrder keys on version, a versioned
milestone always sorts ahead of an unversioned one, and the unversioned tail
falls back to id.
The Vision note now carries a numbered phase table that names which milestones ship in which phase and what each depends on. For the milestones it lists, that table is the real build order.
Those two orders do not meet. Of 74 milestone rows in the index, 25 carry a version and 49 do not. Every milestone in the vision’s phase table is unversioned, so the index sorts them alphabetically by id in the tail while the phase table puts them in a deliberate sequence. A reader of the index sees no order at all for exactly the milestones whose order has been decided.
Three ways out, and the choice is a real decision rather than a cleanup:
- Give the phased milestones versions that match their phase, which makes the index agree and leaves the phase table as the narrative.
- Teach the index to read the phase table, which makes the note the single
source and demotes
versionto a release label. - Say plainly in both places that
versionorders releases while the phase table orders delivery, and accept that the index is not a roadmap.
Whichever is chosen, D-0002-entity-identifier-shape’s claim that semver is the roadmap needs rewording, because for two thirds of the corpus it is not.
Related: B-I5SH-index-milestone-ordering asks the index caption to say where an unversioned milestone lands. That is the smaller half of this.