Invert dependency between core and readable-stream

00X-streams.md

@@ -0,0 +1,55 @@
+| 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 download 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` 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.
+
+## 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.
+
+## Target version of Node
+
+We think we should target this to be shipped in Node 8.