readdir docs don’t mention when options argument was added

[chris-morgan]

fs.readdir(path[, options], callback)

History

Version	Changes
v7.0.0	The callback parameter is no longer optional. Not passing it will emit a deprecation warning.
v0.1.8	Added in: v0.1.8

options was added in Node 6.0.0 by #5616. But it’s not mentioned, which led me to writing generic code that passed through undefined for options, which naturally made it fall apart on the Node 4 LTS release that doesn’t support options and so perceived it as just an undefined callback.

This really worries me. If something like this can change without any note in the history, what else is lacking history of changes that will come and bite me later? I no longer trust this documentation. At least https://nodejs.org/docs/latest-v4.x/api/fs.html#fs_fs_readdir_path_callback is still there, I’ll just need to remember to work there.

[joyeecheung]

The per-item changes in the documentation is added in #11489, which happened much later than the v6.0.0 release, so it's very likely there would be something falling through the cracks. The differences between v4 and v6 are also documented in
https://github.com/nodejs/node/wiki/Breaking-changes-between-v4-LTS-and-v6-LTS.

I agree the missing documentation for previous changes would confuse users, and it definitely needs improvement, though I believe the documentation would be more reliable in future releases, now that we have a system like this in place.

Labeled as a good first contribution, feel free to open a PR to fix this!

(Also, maybe we can open a meta issue to hunt for more missing changelog items? Should not be that hard if we go through the semver-major PRs)

[gibfahn]

Should not be that hard if we go through the semver-major PRs

We'd have to look at semver-minor PRs as well (and check whether/how far they got backported).

[shubheksha]

I'll take this up!