Skip to content

Commit

Permalink
Docs: Improve & fix parts of Getting Started
Browse files Browse the repository at this point in the history
  • Loading branch information
phated committed Jul 29, 2018
1 parent 9f4a2e9 commit 84b0234
Show file tree
Hide file tree
Showing 6 changed files with 59 additions and 30 deletions.
8 changes: 6 additions & 2 deletions docs/getting-started/1-quick-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,17 +52,21 @@ npm install --save-dev gulp
```

### Verify your gulp versions

```sh
gulp --version
```

Ensure the output matches the screenshot below or you might need to restart the steps in this guide.

![Output: CLI version 2.0.1 & Local version 4.0.0][img-gulp-version-command]

### Create a gulpfile
Using your text editor, create a file named gulpfile.js in your project root with these contents:
```js
function defaultTask(done) {
function defaultTask(cb) {
// place code for your default task here
done();
cb();
}

exports.default = defaultTask
Expand Down
40 changes: 32 additions & 8 deletions docs/getting-started/3-creating-tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,17 +160,18 @@ exports.build = series(
);
```

When a composed operation is run, each task will be executed every time it was referenced. For example, a `clean` task referenced before two different tasks would be run twice and lead to undesired results. Tasks can be wrapped with the [async-once][async-once] module if this **(not recommended)** pattern is needed.
When a composed operation is run, each task will be executed every time it was referenced. For example, a `clean` task referenced before two different tasks would be run twice and lead to undesired results. Instead, refactor the `clean` task to be specified in the final composition.

If you have code like this:

```js
// This pattern is NOT recommended but some edge cases might require it.
const { series } = require('gulp');
const once = require('async-once');
// This is INCORRECT
const { series, parallel } = require('gulp');

const clean = once(function(cb) {
const clean = function(cb) {
// body omitted
cb();
});
};

const css = series(clean, function(cb) {
// body omitted
Expand All @@ -180,9 +181,32 @@ const css = series(clean, function(cb) {
const javascript = series(clean, function(cb) {
// body omitted
cb();
})
});

exports.build = parallel(css, javascript);
```

Migrate to this:

```js
const { series, parallel } = require('gulp');

function clean(cb) {
// body omitted
cb();
}

function css(cb) {
// body omitted
cb();
}

function javascript(cb) {
// body omitted
cb();
}

exports.build = series(css, javascript);
exports.build = series(clean, parallel(css, javascript));
```

[async-completion-docs]: 4-async-completion.md
Expand Down
20 changes: 10 additions & 10 deletions docs/getting-started/4-async-completion.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ exports.default = streamTask;

```js
function promiseTask() {
return Promise.resolve('some ignored value');
return Promise.resolve('the value is ignored');
}

exports.default = promiseTask;
Expand Down Expand Up @@ -79,12 +79,12 @@ exports.default = observableTask;

### Using an error-first callback

If nothing is returned from your task, you must use the error-first callback to signal completion. The callback will be passed to your task as the only argument - named `done()` in the examples below.
If nothing is returned from your task, you must use the error-first callback to signal completion. The callback will be passed to your task as the only argument - named `cb()` in the examples below.

```js
function callbackTask(done) {
// `done()` should be called by some async work
done();
function callbackTask(cb) {
// `cb()` should be called by some async work
cb();
}

exports.default = callbackTask;
Expand All @@ -93,9 +93,9 @@ exports.default = callbackTask;
To indicate to gulp that an error occurred in a task using an error-first callback, call it with an `Error` as the only argument.

```js
function callbackError(done) {
// `done()` should be called by some async work
done(new Error('kaboom'));
function callbackError(cb) {
// `cb()` should be called by some async work
cb(new Error('kaboom'));
}

exports.default = callbackError;
Expand All @@ -106,8 +106,8 @@ However, you'll often pass this callback to another API instead of calling it yo
```js
const fs = require('fs');

function passingCallback(done) {
fs.access('gulpfile.js', done);
function passingCallback(cb) {
fs.access('gulpfile.js', cb);
}

exports.default = passingCallback;
Expand Down
6 changes: 3 additions & 3 deletions docs/getting-started/5-working-with-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ exports.default = function() {
}
```

`dest()` is given an output directory string which is generally used as a terminator stream. When it receives a file passed through the pipeline, it writes the contents and other details out to the filesystem at a given directory. The `symlink()` method is also available and operates like `dest()`, but creates links instead of files (see [`symlink()`][symlink-api-docs] for details).
`dest()` is given an output directory string and also produces a [Node stream][node-streams-docs] which is generally used as a terminator stream. When it receives a file passed through the pipeline, it writes the contents and other details out to the filesystem at a given directory. The `symlink()` method is also available and operates like `dest()`, but creates links instead of files (see [`symlink()`][symlink-api-docs] for details).

Most often plugins will be placed between `src()` and `dest()` using the `.pipe()` method and will transform the files within the stream.

Expand All @@ -61,9 +61,9 @@ exports.default = function() {

## Output in phases

`dest()` can be used in the middle of a pipeline to write intermediate states to the filesystem. When a file is received, the current state is written out to the filesystem, the path is updated to represent the new location of the output file, then that file is passed down the pipeline.
`dest()` can be used in the middle of a pipeline to write intermediate states to the filesystem. When a file is received, the current state is written out to the filesystem, the path is updated to represent the new location of the output file, then that file continues down the pipeline.

This feature can be useful to create an unminified and minified file with the same pipeline.
This feature can be useful to create unminified and minified files with the same pipeline.

```js
const { src, dest } = require('gulp');
Expand Down
1 change: 1 addition & 0 deletions docs/getting-started/7-using-plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,7 @@ exports.default = function() {
const code = uglify.minify(file.contents.toString())
file.contents = Buffer.from(code)
}
cb(null, file);
}))
.pipe(dest('output/'));
}
Expand Down
14 changes: 7 additions & 7 deletions docs/getting-started/8-watching-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,17 +15,17 @@ This API provides built-in delay and queueing based on most-common-use defaults.
const { watch, series } = require('gulp');

function clean(cb) {
// Body omitted
// body omitted
cb();
}

function javascript(cb) {
// Body omitted
// body omitted
cb();
}

function css(cb) {
// Body omitted
// body omitted
cb();
}

Expand All @@ -51,7 +51,7 @@ const { watch } = require('gulp');

// All events will be watched
watch('src/*.js', { events: 'all' }, function(cb) {
// Body omitted
// body omitted
cb();
});
```
Expand All @@ -67,7 +67,7 @@ const { watch } = require('gulp');

// The task will be executed upon startup
watch('src/*.js', { ignoreInitial: false }, function(cb) {
// Body omitted
// body omitted
cb();
});
```
Expand All @@ -83,7 +83,7 @@ const { watch } = require('gulp');

// The task will be run (concurrently) for every change made
watch('src/*.js', { queue: false }, function(cb) {
// Body omitted
// body omitted
cb();
});
```
Expand All @@ -99,7 +99,7 @@ const { watch } = require('gulp');

// The task won't be run until 500ms have elapsed since the first change
watch('src/*.js', { delay: 500 }, function(cb) {
// Body omitted
// body omitted
cb();
});
```
Expand Down

0 comments on commit 84b0234

Please sign in to comment.