Gulp: Better document using merge-stream to handle multiple streams being returned

[callumacrae]

A really commonly asked question, and one of the recipes, is how to return multiple streams in one task. The answer is to use merge-stream, of course, but would it be easier for users / cut down the number of support questions if merge-stream were a dependency of gulp and returning an array of streams called it automatically?

So this:

var gulp = require('gulp');
var merge = require('merge-stream');

gulp.task('test', function() {
  var bootstrap = gulp.src('bootstrap/js/*.js')
    .pipe(gulp.dest('public/bootstrap'));

  var jquery = gulp.src('jquery.cookie/jquery.cookie.js')
    .pipe(gulp.dest('public/jquery'));

  return merge(bootstrap, jquery);
});

Would turn into this:

var gulp = require('gulp');

gulp.task('test', function() {
  var bootstrap = gulp.src('bootstrap/js/*.js')
    .pipe(gulp.dest('public/bootstrap'));

  var jquery = gulp.src('jquery.cookie/jquery.cookie.js')
    .pipe(gulp.dest('public/jquery'));

  return [bootstrap, jquery];
});

It's pretty much the same, but a lot simpler to someone who doesn't understand streams or nodejs. Also, really easy to implement.

Thoughts?

[phated]

:-1: on introducing magic into core. People need to learn their tools, including streams and node, if they are using gulp. This is just a documentation issue.

[troch]

I agree with returning an array not being a good solution.
Maybe adding merge-stream or merge2 as a gulp dependency and making gulp.merge available?

[callumacrae]

@phated: I feel it's more an overall issue with the recipes and searchability. Renaming the recipe might help, adding keywords to readme.md in the recipes might help, but I really feel there needs to be a better solution.

I sometimes struggle to find the recipe for merging streams, and I know it's there! I always end up on the combining streams one, which is the wrong one. "Using multiple sources in one task" is not the easiest to find for me—but for some people, it'll be the first thing they search for.

What happened with the docs project in the end? I was pretty busy at the time, but I have more time if you want someone to lead something like that.

[contra]

@callumacrae We are moving documentation to readme.io, I think I sent you an invitation a while ago to help out. readme.io gives us better organization and search + documentation with good versioning

[callumacrae]

Indeed, I'm in now. Forgot what it was called and couldn't find the email :)

I'll take a look to see what I can do over the weekend

[phated]

@callumacrae my thoughts are to explicitly add a merge-stream example to the README sample also. And maybe even in the API docs.

[laurencedorman]

Is help still wanted on this one?

[phated]

Yep!