CLI multiple tasks - docs should specify semantics

[kylecordes]

What were you expecting to happen?

I expect the documentation for the CLI to plainly state the semantics of listing more than one task.

https://github.com/gulpjs/gulp/blob/master/docs/CLI.md

In more detail, this documentation should state whether, when multiple tasks are listed, they will be executed concurrently, or sequentially. Here is a common practical application. Imagine I have a task "clean" and a task "build". Is it valid to run the command "gulp clean build"? If the semantics were specified, then I could answer this question.

What actually happened?

It does not specify the semantics. It says only "Tasks can be executed by running gulp ."

Please post a sample of your gulpfile (preferably reduced to just the bit that's not working)

n/a, looking at the current CLI documentation linked above.

What version of gulp are you using?

n/a, looking at the current CLI documentation linked above.

What versions of npm and node are you using?

n/a, looking at the current CLI documentation linked above.

[callumacrae]

PR welcome! :)

[kylecordes]

@callumacrae But what are the semantics? You are a core team member, your answer has credibility as the official answer. Let me know here and I will happily put together the actual PR.

[kylecordes]

A bit of research in the code reveals that multiple tasks listed are passed onward to https://www.npmjs.com/package/orchestrator where they are executed concurrently.

I will work on a doc PR.

[kylecordes]

Update: looking at the code it appears they will happen concurrently. But experimentally they seem to happen sequentially. So it seems like I should wait for an official answer for working on a doc change.

[callumacrae]

Ah sorry, didn't realise it was a question too. I'm not actually sure what happens - @contra or @phated should know though.

[phated]

They are run the same way task dependencies are run (when specified with ['task1', 'task2']), which orchestrator calls "maximum concurrency". If you are only writing sync tasks, they aren't going to be run in parallel (that's not how JS works) but async tasks should be run in parallel. This is yet-another-reason why we are removing sync tasks in the next version.

This documentation should also be updated in the gulp-cli repository.

Going to close this as a duplicate of #1595 because all our documentation needs work.

[kylecordes]

@phated Would you be interested in a PR which improves this specific aspect of the CLI docs, this week? Or do you prefer to leave it as it is until the eventual epic rewrite?

[phated]

@kylecordes sure!