From fed3a3f7d29ac484431da04f40fca59684ad28db Mon Sep 17 00:00:00 2001 From: Matteo Collina Date: Sun, 22 Jan 2017 12:46:10 -0500 Subject: [PATCH] Invert dependency between core and readable-stream --- 00X-streams.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 00X-streams.md diff --git a/00X-streams.md b/00X-streams.md new file mode 100644 index 0000000..5a4c15a --- /dev/null +++ b/00X-streams.md @@ -0,0 +1,97 @@ +| Title | Invert dependency of readable-stream | +|--------|--------------------------------------| +| Author | @mcollina | +| Status | DRAFT | +| Date | 2017-01-26 12:00:00 | + +## Description + +The `readable-stream` module is one of the most popular modules on NPM, +with 33 million downloads per month. `readable-stream` is the basis of +most of the ecosystem utilities for manipulating streams, as it provides +a consistent API across all the different versions of Node.js and the +browser: from Node.js v0.8, and IE 9 and Safari 5 as the oldest browsers. + +`readable-stream` was introduced to help module authors build the +streams ecosystem across the different versions of Node.js, backporting +v0.10 streams to v0.8. +The code for the `'stream'` module in core *depends on the version of +core* that is being used, and because streams users inherits from +classes like `Readable`, `Writable` or `Transform` a tiny difference +might make a program work on a version of Node but not in another. +Module authors appreciate the stability `readable-stream` provides, +and it is currently in the dependency tree of gulp, mysql, mongodb, webpack +and many other highly-popular libraries. +A good article for what `readable-stream` provides can be found at +https://r.va.gg/2014/06/why-i-dont-use-nodes-core-stream-module.html. + +`readable-stream` is an export of the latest stream API from the Node.js, +done via a mixture of babel transpiling and regular expressions. The export +means that `readable-stream` has to follow the Node.js release cycle, and it +is not versioned independently. Specifically, versioning of `readable-stream` +is extremely hard, as *we are currently not bumping major* +to avoid breaking many packages and maintaining multiple lines. The current +situation is not ideal, as `readable-stream` passively follows what is merged +in Node.js. + +At the moment `readable-stream` does not have its own documentation, it is the +documentation of whichever version of Node.js is built from. This creates confusion, +as the latest `stream` from Node.js supports some features that cannot be ported +to all versions of Node.js. + +This EP proposes to invert that dependency, and have Node.js include +readable-stream from the `deps` folder. + +## SEMVER for streams + +As things stands right now, `readable-stream` support Node.js from v0.8 +upwards, and fairly ancient browsers versions as well. Because of this, +we are currently using babel (and a bunch of regexps) before release, +to support ES5-based vendors. Dropping support for any of those is a +semver-major change, and given the massive amount of dependencies, it +might have a semver-major ripple effect throughout the ecosystem. +In order to avoid a lot of work for maintainers, we aim to minimize those. +At the time of this writing, we plan __not to bump__ semver-major in 2017. + +We recognize that the ecosystem is changing at a fast pace, and at some +point we would have to bump the major. If we decide to do that, we would +have to manage two release lines (or more), and backport changes from +Node.js streams to **both**. As things are now, this is highly +impractical to do, and it would be much easier to manage if `readable-streams` +could manage its own versioning. + +## Process / Timeline + +1. move the code of streams into `readable-stream` +2. amend the build script for the NPM/ecosystem build +3. rewrite the tests to easily check against both the node + source folder and old versions of Node.js and the browser. +4. port the Node streams documentation to `readable-stream`; a _copy_ + of the docs will be maintained in Node.js. +4. merge back all changes that happened in the meanwhile, and sync up +5. add `nodejs/readable-stream` inside deps of Node.js, and remove the streams + implementation; to avoid any possible disruption, this will be a + _semver-major_ change for Node.js. +6. bump *minor* version of `readable-stream`. + +## Challenges + +1. export git history from node.js +2. handling issues between the two repositories + +These challenges need to be adressed with the rest of the node collaborators. + +## Role of the Streams WG + +The Streams Working Group will still be responsible for maintaining +`readable-stream` and `'streams'` in core, and this EP does not change +anything. However, the role of `readable-stream` is to +`'port stream to older node versions and browsers'`, while after the +inversion of dependency, it would change to `'support Node.js streams in +throughout the different versions of Node and browsers'`. +As it is right now, the Streams WG commits in maintaining the +performance of streams within Node.js. + +## Target version of Node + +We think we should target this to be shipped in Node 8.