Meta: Review Draft infrastructure

See whatwg/whatwg.org#197 and whatwg/meta#92 for details.

This also makes various updates to align more with other WHATWG standards, notably in the README and in the addition of a Makefile.

.editorconfig

@@ -14,5 +14,5 @@ max_line_length = 120
 [.gitmodules]
 indent_style = tab
 
-[deploy.sh]
-indent_size = 4
+[Makefile]
+indent_style = tab

.gitignore

@@ -3,3 +3,5 @@
 /streams.spec.whatwg.org/
 /index.html
 /index.html.*
+/deploy.sh
+/review.sh

.travis.yml

@@ -5,17 +5,20 @@ sudo: false
 env:
   global:
     - ENCRYPTION_LABEL="4a24edc7e7d1"
-    - POST_BUILD_STEP='node_modules/.bin/emu-algify --throwing-indicators < "$DIR/index.html" > "$DIR/index.tmp.html"; mv "$DIR/index.tmp.html" "$DIR/index.html"; cp -a demos "$DIR"'
+
 before_install:
   - cd reference-implementation
+
 script:
   - npm test
   - cd ..
   - npm install
-  - curl --remote-name --fail https://resources.whatwg.org/build/deploy.sh && bash ./deploy.sh
+  - make deploy
+
 branches:
   only:
     - master
+
 notifications:
   email:
     on_success: never

CONTRIBUTING.md

@@ -4,16 +4,6 @@ These are the guidelines for contributing to the Streams Standard. First see the
 
 We label [good first issues](https://github.com/whatwg/streams/labels/good%20first%20issue) that you could help us fix, to get a taste for how to submit pull requests, how the build process works, and so on.
 
-## Pull requests
-
-Try to follow the [spec editorial conventions](#spec-editorial-conventions) below.
-
-Follow the [guidelines for writing good commit messages](https://github.com/whatwg/meta/blob/master/COMMITTING.md).
-
-Merge commits are not allowed; history must stay linear.
-
-If you are updating the spec, also update the corresponding parts of the reference implementation where applicable, in the same commit.
-
 ## Spec editorial conventions
 
 Wrap lines to 120 columns. (This is not yet consistently followed.)
@@ -49,26 +39,16 @@ Use single quotes.
 
 Pass ESLint.
 
-## Building the spec
-
-Building the spec is a two-step process. First, the majority of the conversion work is done via [Bikeshed](https://github.com/tabatkins/bikeshed). Second, we run a custom portion of the [Ecmarkup](https://github.com/bterlson/ecmarkup) pipeline to convert the algorithms from [Ecmarkdown](https://github.com/domenic/ecmarkdown) syntax into HTML, and to automatically add cross-references. This second step requires a recent version of [Node.js](https://nodejs.org/en/) to be installed.
-
-### Local "deploy"
-
-To get the full build experience, including commit and branch snapshots, you can run
-
-```
-bash ./deploy.sh --local
-```
+## Notes on building the standard
 
-This will output a bunch of files to the `streams.spec.whatwg.org` directory, equaling those that would be uploaded to the server on deploy. It will use Bikeshed hosted on the CSSWG server, so you do not need to install Bikeshed locally (but will need Node.js).
+The basics of building the standard are explained in the README. Here are some more details that might be interesting.
 
-### Local watch
+Building the standard is a two-step process. First, the majority of the conversion work is done via [Bikeshed](https://github.com/tabatkins/bikeshed). Second, we run a custom portion of the [Ecmarkup](https://github.com/bterlson/ecmarkup) pipeline to convert the algorithms from [Ecmarkdown](https://github.com/domenic/ecmarkdown) syntax into HTML, and to automatically add cross-references. This second step requires a recent version of [Node.js](https://nodejs.org/en/) to be installed, and running `npm install` to install the Ecmarkup/Ecmarkdown tools.
 
-If you have Bikeshed [installed locally](https://tabatkins.github.io/bikeshed/#installing), and have run `npm install`, you can try running
+If you have Bikeshed [installed locally](https://tabatkins.github.io/bikeshed/#installing), we have a special script to continuously build the standard. Doing
 
 ```
 npm run local-watch
 ```
 
-to start a watcher on `index.bs` that will update `index.html` as you edit.
+will start a watcher on `index.bs` that will update `index.html` as you edit.

Makefile

@@ -0,0 +1,17 @@
+remote: index.bs
+	curl https://api.csswg.org/bikeshed/ -f -F [email protected] > index.html.postbs -F md-Text-Macro="SNAPSHOT-LINK LOCAL COPY"
+	node_modules/.bin/emu-algify --throwing-indicators < index.html.postbs > index.html
+
+local: index.bs
+	bikeshed spec index.bs index.html.postbs --md-Text-Macro="SNAPSHOT-LINK LOCAL COPY"
+	node_modules/.bin/emu-algify --throwing-indicators < index.html.postbs > index.html
+
+deploy: index.bs
+	curl --remote-name --fail https://resources.whatwg.org/build/deploy.sh
+	EXTRA_FILES="demos/**/*" \
+	POST_BUILD_STEP='node_modules/.bin/emu-algify --throwing-indicators < "$$DIR/index.html" > "$$DIR/index.html.tmp"; mv "$$DIR/index.html.tmp" "$$DIR/index.html"' \
+	bash ./deploy.sh
+
+review: index.bs
+	curl --remote-name --fail https://resources.whatwg.org/build/review.sh
+	bash ./review.sh

README.md

@@ -1,22 +1,56 @@
 # Streams Standard
 
-The streams standard provides APIs for creating, composing, and consuming streams of data. These streams are designed to map efficiently to low-level I/O primitives, and allow easy composition with built-in backpressure and queuing.
+This repository hosts the [Streams Standard](https://streams.spec.whatwg.org/).
 
-The main spec is available at https://streams.spec.whatwg.org/, generated from the `index.bs` file.
+## Contribution opportunities
 
-Snapshots of any given commit or branch are available at specially-crafted URLs:
+Folks notice minor and larger issues with the Streams Standard all the time and we'd love your
+help fixing those. Pull requests for typographical and grammar errors are also most welcome.
 
-- https://streams.spec.whatwg.org/commit-snapshots/ contains snapshots of any given commit
-- https://streams.spec.whatwg.org/branch-snapshots/ contains snapshots of the latest commit to any given branch
+We'd be happy to mentor you through this process. If you're interested and need help getting
+started, leave a comment on the issue or ask around [on IRC](https://whatwg.org/irc).
 
-## Tests and reference implementation
+## Pull requests
 
-This repository also includes a reference implementation and test suite under `reference-implementation/`. See the README under that directory for more details. We strive for every commit that changes the spec to also add tests, and to change the reference implementation in order to pass those tests.
+In short, change `index.bs` and submit your patch, with a
+[good commit message](https://github.com/whatwg/meta/blob/master/COMMITTING.md). Consider
+reading through the [WHATWG FAQ](https://whatwg.org/faq) if you are new here.
 
-## Contribution guidelines
+Please add your name to the Acknowledgments section in your first pull request, even for trivial
+fixes. The names are sorted lexicographically.
 
-For guidelines on how to build and edit the spec and reference implementation, see [CONTRIBUTING.md](CONTRIBUTING.md).
+For formatting specific to this standard, see [CONTRIBUTING.md](CONTRIBUTING.md). Additionally, for
+any normative changes, we'll also want to change the tests and reference implementation:
+
+## Tests
+
+Tests can be found in the `streams/` directory of
+[`web-platform-tests/wpt`](https://github.com/web-platform-tests/wpt).
+
+## Reference implementation
+
+This repository also includes a reference implementation, written in JavaScript, under
+`reference-implementation/`. See the README under that directory for more details.
+
+We strive for every commit that changes the spec to also add tests, and to change the reference
+implementation in order to pass those tests.
+
+## Building "locally"
+
+This standard requires a recent version of [Node.js](https://nodejs.org/en/) to be installed as a
+prerequisite. Once that's done, you'll need to do a one-time run of `npm install` to set up our
+tooling.
+
+For quick local iteration, run `make`. To verify your changes locally, run `make deploy`. See more
+in the
+[WHATWG Contributor Guidelines](https://github.com/whatwg/meta/blob/master/CONTRIBUTING.md#building).
+
+## Merge policy
+
+If you can commit to this repository, see the
+[WHATWG Maintainer Guidelines](https://github.com/whatwg/meta/blob/master/MAINTAINERS.md).
 
 ## Code of conduct
 
-We are committed to providing a friendly, safe and welcoming environment for all. Please read and respect the [WHATWG Code of Conduct](https://whatwg.org/code-of-conduct).
+We are committed to providing a friendly, safe, and welcoming environment for all. Please read and
+respect the [WHATWG Code of Conduct](https://whatwg.org/code-of-conduct).

reference-implementation/README.md

@@ -16,7 +16,7 @@ To run all tests (and the lint step), run `npm test` in this folder.
 
 ### Web platform tests
 
-The test suite for this standard is written in [web platform tests](https://github.com/w3c/web-platform-tests) format.
+The test suite for this standard is written in [web platform tests](https://github.com/web-platform-tests/wpt) format.
 
 - To run the web platform tests, type `npm run wpt` in this folder.
 - To run specific test files, you can use a glob pattern, rooted at the streams directory: `npm run wpt -- "writable-streams/**"`
@@ -27,7 +27,7 @@ The test runner here is a Node.js emulated-DOM environment, with the reference i
 
 #### Upstream web platform tests
 
-The web platform tests for streams are found in the [streams directory](https://github.com/w3c/web-platform-tests/tree/master/streams) of the web platform tests repository, and maintained via pull requests to that repository. They are then pulled into this repository via a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules).
+The web platform tests for streams are found in the [streams directory](https://github.com/web-platform-tests/wpt/tree/master/streams) of the web platform tests repository, and maintained via pull requests to that repository. They are then pulled into this repository via a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules).
 
 This means that in order to land a test change for these tests, you'll need to make a pull request to the web platform tests repository, and then update the submodule pointer in this repository (probably in the same pull request as your spec change). That can be done via the command