diplodoc-platform / diplodoc-platform/cli
v6: make GenericIncluder `orderBy: natural` the default
- Dominant language
- TypeScript
- Stars
- 123
- Forks
- 51
- Avg merge
- 10h 50m
- Merged PRs (30d)
- 38
Description
## Proposal
In v6, flip the default of `GenericIncluder`'s `orderBy` option to `'natural'` (currently unset → no sort).
## Motivation
#1871 reports that numerically-named docs (`1.md`, `2.md`, …, `20.md`, `100.md`) appear in nonsensical order when using `GenericIncluder`, because the includer historically had `// TODO: implement sort` and emitted items in `glob`/FS + JS object key order.
#1901 adds opt-in `orderBy: 'natural' | 'filename'` and `order: 'asc' | 'desc'` options. Setting `orderBy: 'natural'` resolves the issue today, but the default still produces the bad order out of the box.
Flipping the default is a behavior change observable to every existing `GenericIncluder` user: their generated TOCs will reorder on upgrade. This kind of default flip is exactly what v6 is for, similar to #1900 (`linkIndexAutotitle` default flip).
## Acceptance criteria
- [ ] Default `orderBy` becomes `'natural'`
- [ ] Existing snapshot tests for unsorted output are updated/removed
- [ ] Changelog entry under "Breaking changes"
## Related
- Bug: #1871
- Implementation PR: #1901
- v6 tracking: #1899
Contributor guide
Assessment
This issue has not been assessed yet.