VERSION_NOTES.md is misleading

[jfirebaugh]

Support plan

• Which support plan is this issue covered by? (Community, Sponsor, Enterprise): Community
• Currently blocking your project/work? (yes/no): no
• Affecting a production system? (yes/no): no

Context

• Node.js version: n/a
• Release Line of Formidable (Legacy, Current, Next): "Current" / v2
• Formidable exact version: 2.0.6
• Environment (node, browser, native, OS): n/a
• Used with (popular names of modules): n/a

What are you trying to achieve or the steps to reproduce?

VERSION_NOTES.md does not explicitly say that v2 has any breaking changes compared to v1 other than "requiring newer Node.js versions". In contrast, it says for v3 "Dropping v1 compatibility". This strongly implies, and most people who are not contributors would naturally assume, that v2 is API compatible with v1.

What was the result you got?

However, that is not the case. There are a number of API changes between v1 and v2. For example, the following entries from CHANGELOG.md appear to be breaking API changes:

• rename: option.hash into option.hashAlgorithm (Safe default filename #689)
• rename: file.path into file.filepath (Safe default filename #689)
• rename: file.type into file.mimetype (Safe default filename #689)
• refactor: split file.name into file.newFilename and file.originalFilename (Safe default filename #689)

What result did you expect?

It would be helpful if VERSION_NOTES.md listed the API changes, or at least explicitly stated that v2 is not API compatible with v1. For example, "Dropping v1 compatibility" could be moved to the section on v2 instead of the section on v3.