New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs] Migration Guide #861

Open
johnpapa opened this Issue Jan 11, 2015 · 36 comments

Comments

@johnpapa
Copy link

johnpapa commented Jan 11, 2015

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

@phated

This comment has been minimized.

Copy link
Member

phated commented Jan 11, 2015

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

@johnpapa

This comment has been minimized.

Copy link

johnpapa commented Jan 11, 2015

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

This comment has been minimized.

Copy link
Member

phated commented Jan 11, 2015

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

This comment has been minimized.

Copy link

johnpapa commented Jan 11, 2015

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

This comment has been minimized.

Copy link

johnpapa commented Jan 11, 2015

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

This comment has been minimized.

Copy link
Member

phated commented Jan 11, 2015

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

This comment has been minimized.

Copy link

johnpapa commented Jan 11, 2015

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

This comment has been minimized.

Copy link
Member

phated commented Jan 11, 2015

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

@johnpapa

This comment has been minimized.

Copy link

johnpapa commented Jan 12, 2015

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

This comment has been minimized.

Copy link

dmackerman commented Jan 15, 2015

@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

This comment has been minimized.

Copy link

johnpapa commented Jan 24, 2015

yes, that's what i did :)

@johnpapa

This comment has been minimized.

Copy link

johnpapa commented Jan 30, 2015

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

@johnnyreilly

This comment has been minimized.

Copy link

johnnyreilly commented Jan 30, 2015

Great to hear about the course @johnpapa 👍

@phated

This comment has been minimized.

Copy link
Member

phated commented Mar 14, 2015

An update on this: the 4.0 branch now has all the docs updated thanks to @dinoboff - this should make a migration guide a lot easier

@johnnyreilly

This comment has been minimized.

Copy link

johnnyreilly commented Mar 14, 2015

Great to hear! Any news on when 4.0 will be officially released?

@Keats

This comment has been minimized.

Copy link

Keats commented Mar 17, 2015

Wrote an article showing how to migrate an example boilerplate: https://blog.wearewizards.io/migrating-to-gulp-4-by-example

Let me know if I got anything wrong and/or missing !

@phated phated added the help wanted label Mar 22, 2015

@phated phated referenced this issue Mar 22, 2015

Closed

Bring in new task system (bach) #355

4 of 4 tasks complete
@ilanbiala

This comment has been minimized.

Copy link

ilanbiala commented Mar 22, 2015

@phated can't this be closed now that @johnpapa has a migration guide and @Keats put together an article? The big issue now with documentation is probably updating the recipes, which should be a separate Gulp 4 documentation issue, no?

@phated

This comment has been minimized.

Copy link
Member

phated commented Mar 22, 2015

@ilanbiala yeah, we just need to consolidate all the information into a docs/upgrading.md and make sure everything is covered.

@dinoboff

This comment has been minimized.

Copy link
Contributor

dinoboff commented Mar 22, 2015

@ilanbiala the recipes should be using the new API correctly. They might no show the best practices however.

Maybe we're missing some recipe updates from master too.

@callumacrae

This comment has been minimized.

Copy link
Member

callumacrae commented Oct 2, 2015

@phated I arranged to write a migration guide with Smashing Magazine aages ago without seeing this issue. Do you think there's any way we could use it to solve this issue? I could speak to them to ask about reposting it with a link back to the original.

@phated

This comment has been minimized.

Copy link
Member

phated commented Oct 2, 2015

@callumacrae +1000 - please reach out to them. Also, can you send me a link so I can read through it? There's bound to be some recent changes that probably weren't addressed.

@callumacrae

This comment has been minimized.

Copy link
Member

callumacrae commented Oct 6, 2015

Haven't actually written it yet, it's just a very messy bit of paper at the moment! The plan was to publish it at about the same time Gulp 4 is released. I should probably get writing 😄

Will send it to you for a read through when it's readable.

@phated

This comment has been minimized.

Copy link
Member

phated commented Apr 5, 2016

@callumacrae were you able to make progress on this?

@callumacrae

This comment has been minimized.

Copy link
Member

callumacrae commented Apr 5, 2016

Have done a fair amount. The list of things left to do for gulp 4 is pretty small now, so will get back on it :)

@phated phated modified the milestone: gulp 4 - latest tag Jun 28, 2016

@phated phated added this to Docs in Gulp 4 Mar 8, 2017

@phated

This comment has been minimized.

Copy link
Member

phated commented Mar 21, 2017

@AndrewGuenther calling something we've put a ton of time into "horrendous" isn't a way to get involved. I'll be removing your comment and hope you don't bring that negativity back in the future.

@AndrewGuenther

This comment has been minimized.

Copy link

AndrewGuenther commented Mar 21, 2017

@phated apologies for the inflammatory wording, let me try again.

Hi, I would love to help with a Gulp 4 migration guide. For large projects, the new task model can be quite difficult to reason about and migration can be complicated. I would like to help others so that maybe it won't be as painful for them as it was for me.

@phated

This comment has been minimized.

Copy link
Member

phated commented Mar 21, 2017

@AndrewGuenther thank you. You're insight would be very appreciated on the migration guide.

I actually designed a lot of niceties into the API to help large projects, inspired by some projects I worked on. An example of this is custom task registries, which allow for custom logic or sharing tasks across many projects within an organization.

@AndrewGuenther

This comment has been minimized.

Copy link

AndrewGuenther commented Mar 21, 2017

@phated custom registries was probably the biggest win for us in the migration. Awesome work!

The biggest issue for us was the removal of the dependency tree. I think providing clear best practices for the new task model and how to avoid running tasks multiple times while ensuring subtasks still function as expected is going to be really important for larger projects.

@Saturate

This comment has been minimized.

Copy link

Saturate commented Jun 29, 2017

I made a very simple code mod for some of the changes needed: https://gist.github.com/Saturate/243f68359f2f32ba4db5d16da002bed4

It can be expanded as needed.

@phated

This comment has been minimized.

Copy link
Member

phated commented Dec 20, 2017

Who has watch usage in their migration guide? It's changed pretty drastically over previous versions and I'd like to get it documented properly.

@phated

This comment has been minimized.

Copy link
Member

phated commented Dec 21, 2017

We also need to let people know that they can't build globs with path.join anymore because Windows separators aren't valid glob separators.

@gchamon

This comment has been minimized.

Copy link

gchamon commented Jul 1, 2018

How is the state of this migration guide? I have very recently (2 days ago) finished migrating a build/serve/watch solution successfuly and although there are some blogs here and there with somewhat comprehensive guides, it doesn't really touch many issues in a centralized and pragmatic way.
So, if there is interest, I could help writing guidelines in refactoring and upgrading a gulp solution from 3 to 4.
The main motivation was moving away from bower, resolving packages with Yarn, but then the glob used with gulp.src in v3 doesn't really like that and would yell at me everytime I needed to look inside the recently resolved folder. I was feeling like chasing my tail and decided to just upgrade it and it went really well, and is in fact a faster solution.

@niksy niksy referenced this issue Jul 5, 2018

Closed

Upgrade to Gulp v4 #93

@phated

This comment has been minimized.

Copy link
Member

phated commented Jul 29, 2018

We'd love someone to submit a proper Migration Guide as a PR that we could review. It's very far down our list of documentation to complete. We just merged our new Getting Started guide so that would be a good series to become familiar with before creating the Migration Guide (in order to migrate to the new recommended patterns).

Side note: It'd be awesome to have a codemod for migrations.

@janiceilene

This comment has been minimized.

Copy link
Member

janiceilene commented Sep 24, 2018

We've finished the Getting Started Guide, we're submitting the new API documentation very soon, and working on the new documentation website! The Migration Guide is still on our to do list, but it'll be quite a while until we get to it. Is anyone still interested in helping me create one based on the new recommended patterns from the Getting Started Guide?

@johnpapa @dmackerman @johnnyreilly @Keats @stevelacy @ilanbiala @dinoboff @callumacrae @AndrewGuenther @Saturate @gchamon

@gchamon

This comment has been minimized.

Copy link

gchamon commented Sep 25, 2018

Hey there! I was trying to bring myself to writing the draft of a guide, but I had many issues the past couple of months. It is starting to settle now.

I have to get my examples and migrate them away of using magic strings. I kind of like using strings for each function so I have some degree of granularity when testing the task flow, but I can see why it is not recommended. It can get messy.

There are other issues with my coding style. I have to review the style guide anyway. I can, however try to help people having issues. I became the sole maintainer of the gulp scripts we have at work and I feel quite comfortable with it.

@phated phated changed the title Migration Guide [Docs] Migration Guide Oct 25, 2018

@phated

This comment has been minimized.

Copy link
Member

phated commented Oct 25, 2018

Would anyone like to submit a PR for this???

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment