diplodoc-platform / diplodoc-platform/cli

v6: make GenericIncluder `orderBy: natural` the default

Open
#1,902 0 comments 0 reactions 0 assignees View on GitHub
major
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.