[Docs] Migration Guide

[johnpapa]

I'm interested in contributing to a migration guide from 3 --> 4. Are there any starting points already in progress?

[phated]

The changelog and readme on https://github.com/gulpjs/gulp/tree/4.0 are the best places to start for migrating.

[johnpapa]

I started migrating a gulpfile and there was a quick path and a better path. I think it would be a great idea to include both in the migration story. For example, for the most part you can start replacing the old array of string names with gulp.parallel. However if you have nested task dependencies, this could get ugly. But yes, it works and its the quick path.

Quick path:

1. replace array of dependency task names with gulp.parallel( ... )
2. re-sequence the tasks in the order they are defined and used

Better path:

1. Make everything a function
2. Always return the stream or call the cb, but that was good practice in Gulp 3 too
3. Use gulp.parallel and gulp.series to replace dependency arrays.
4. Now that you are calling functions, be sure to add the parallel and series in the right sequence.

I'll tidy that all up with examples, but I was able to follow this loosely today and I removed several tasks. Commented ones went away in Gulp 4 as I no longer had a need for them.

// don't need these to be tasks anymore. embedded them
//gulp.task('clean-code' ...
//gulp.task('clean-fonts' ...
//gulp.task('clean-images' ...
//gulp.task('clean-styles' ...
gulp.task('vet', vet); // jshint and such
gulp.task('plato', plato);
gulp.task('clean', clean);
gulp.task('styles', styles);
//gulp.task('fonts', gulp.series(fonts)); // now part of build
//gulp.task('images', gulp.series(images)); // now part of build
gulp.task('less-watcher', lessWatcher);
//gulp.task('templatecache', gulp.series(templatecache));
gulp.task('inject-bower', injectBower);
//gulp.task('build-specs', gulp.series(templatecache, buildSpecs)); // part of serve-specs
gulp.task('serve-specs', gulp.series(templatecache, buildSpecs, serveSpecs));
gulp.task('test', gulp.series(vet, templatecache, test));
gulp.task('autotest', gulp.series(templatecache, autotest));
gulp.task('build', build); //not really needed, just a nice gut check
gulp.task('serve-dev', gulp.series(injectAll, serveDev));
gulp.task('serve-build', gulp.series(test, build, serveBuild));
gulp.task('bump', bump);

[phated]

Very cool. I'd like to also mention removing run-sequence and gulp.start/gulp.run usage. start/run are completely removed and run-sequence module is no longer needed due gulp.series. I think run-sequence will actually no longer work due to start/run removal also, but not sure.

[johnpapa]

Right, good calls. Here is what I have gleaned so far

• Key is the sequencing and parallelism of tasks
• replaced dependent tasks with parallel and series
• integrated sourcemaps
• deprecated
  • gulp.start
  • gulp.run
  • string array task dependencies replaced by series and parallel
  • gulp-util split into modules

Note: gulp-task-listing no longer works, due to the new task system. Would be good to create a new plugin for that as I use it as my default task.

[johnpapa]

I also have a before and after gulpfile I will show.

of course this all depends on when it is widely available as a RC or RTW, when the API is frozen

[phated]

gulp-task-listing might need to be blacklisted. I'm thinking about it still. What is wrong with one of the many command line flags available? --tasks, --tasks-simple, --tasks-json are all available in gulp4

[johnpapa]

It's a great plugin (for gulp 3).

I like the output from gulp --tasks-simple. Would be nice to make that the default. I guess I could write some node code inside of the gulpfile to run that when gulp is called as the default task.

Often when folks are looking at a gulpfile they may not know what tasks are there.This is not documentation, but a remiinder of the task names. Having it as the default task makes it dead simple for them. What if they don't recall --tasks-simple?

It's not a major thing and I'm not asking for a code change, just explaining where I have seen value in it.

[phated]

The CLI is getting a help menu and there is a new method gulp.tree that will give you the task tree.

[johnpapa]

Cool. Had not seen that yet.

I've found that it has been helpful to create a object literal named recipes to declare all of my series/parallel tasks that I reuse. Some do not need this, and I call the functions from a task. Here is an example of each.

I found this useful and pushed to my local repo some working examples. I'll share more widely once v4 goes RC.

// Simple task --> function
function jshint() {
    return gulp
        .src(config.alljs)
        .pipe($.jshint())
        .pipe($.jshint.reporter('jshint-stylish', {verbose: true}))
        .pipe($.jshint.reporter('fail'));
}

gulp.task('jshint', jshint);

// Simple task --> series/parallel 
function templatecache() {
    log('Creating an AngularJS $templateCache');

    cleanFiles(config.temp + '**/*.js');

    return gulp
        .src(config.htmltemplates)
        .pipe($.minifyHtml({empty: true}))
        .pipe($.angularTemplatecache(
            config.templateCache.file,
            config.templateCache.options
        ))
        .pipe(gulp.dest(config.temp));
}

function autotest(done) {
    startTests(false /* singleRun */, done);
}

gulp.task('autotest', gulp.series(templatecache, autotest));

// Recipes are series or parallel sets of tasks that can be reused
// i.e. recipes.injectAll
var recipes = {};
recipes.injectAll = gulp.series(gulp.parallel(injectBower, styles, templatecache),
                                injectCSS);

function serveDev() {
    var nodeOptions = {
        script: config.nodeServer,
        delayTime: 1,
        env: {
            'PORT': port,
            'NODE_ENV': 'dev'
        },
        watch: [config.server]
    };

    return $.nodemon(nodeOptions);
}

gulp.task('serve-dev', gulp.series(recipes.injectAll, serveDev));

// Now recipes.injectAll is reused by another recipe
recipes.build = gulp.series(recipes.test,
                        gulp.parallel(images, fonts, recipes.injectAll),
                        gulp.series(optimize, function() { 
                            // wrap up code
                        }));

[dmackerman]

@johnpapa, how did you go about getting v4 running in your project? I'd like to start migrating our gulpfile, but I'm confused as to how you got v4 working properly?

EDIT: Silly me, realized I can just specify a git repo and branch name for my local gulp. duh.

[johnpapa]

yes, that's what i did :)

[johnpapa]

FYI - my gulp course is now out, and I included a first look at gulp 4 at the end.
http://jpapa.me/gulpps

[johnnyreilly]

Great to hear about the course @johnpapa 👍