Giters

node-formidable / formidable

The most used, flexible, fast and streaming parser for multipart form data. Supports uploading to serverless environments, AWS S3, Azure, GCP or the filesystem. Used in production.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

VERSION_NOTES.md is misleading

jfirebaugh opened this issue · comments

commented

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 (#689)
  • rename: file.path into file.filepath (#689)
  • rename: file.type into file.mimetype (#689)
  • refactor: split file.name into file.newFilename and file.originalFilename (#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.