Skip to content
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

Build systems > Gulp #3

Open
addyosmani opened this issue Dec 26, 2013 · 36 comments
Open

Build systems > Gulp #3

addyosmani opened this issue Dec 26, 2013 · 36 comments
Assignees
Labels

Comments

@addyosmani
Copy link
Member

Gulp is a streaming build system. Like Grunt, but faster and less config. There currently aren't a lot of tutorials about Gulp out there at the moment.

It would be useful to cover some of the same items in #2, but with a focus on using Gulp plugins, talking about how it differs from other build systems etc.

@sindresorhus
Copy link
Contributor

@travm might be interested as he has written a couple of articles on Gulp.

@addyosmani
Copy link
Member Author

Thanks @sindresorhus! Being relatively new there are still a lot of best practices around Gulp that have yet to be documented and I'd love to see a chapter on it in here.

@travm
Copy link
Contributor

travm commented Dec 27, 2013

I'd be glad to help out. Just let me know how we'll be organizing the information and where to begin work.

@addyosmani
Copy link
Member Author

Fantastic. Will let you know as soon as we have the basic setup for contributing committed.

@addyosmani
Copy link
Member Author

Okay, now that we've got the basics for #8 (build system) in place, I think we're ready to start accepting contributions. @travm would you like to propose what topics a Gulp chapter should ideally cover? Would love to have you author if you'd be down for that.

@travm
Copy link
Contributor

travm commented Dec 27, 2013

Using what was mentioned in issue #9 by @rowoot I think this would be a good start.

  • Introduction
    • Why Gulp?
    • How Is It Different?
  • Getting started
    • Installation (How Detailed Should This Be?)
    • Debugging (Common Installation/Getting Started Issues - or should this be included in the final section below?)
  • gulp Specific/Simple Code Walkthroughs
    • Adding A Linter
    • CSS Preprocessing
    • Local Server/Live Reload
    • Running Tests
    • Deployment
  • Best Practices
  • Troubleshooting/Common Issues

How detailed would we want the installation notes to be? Since most Node tools will share a similar installation process, should we start from the very base of installing Node? Or, should we assume that the reader has already viewed the introduction chapter for Node and npm?

@addyosmani
Copy link
Member Author

That looks like a great start. I would say we should assume that Node and npm are already available and setup. We'll cover how to do this in the first chapter so that there doesn't have to be repetition there. We can always refer readers back if they aren't familiar with the tools needed to setup :)

@michealbenedict
Copy link
Contributor

I like @travm's idea of having code walkthroughs (assuming these are links to plunkr/jsbin/jsfiddle) as part of the tool specific content. I somewhat feel that there could be an overlap between "Best practices" content and the tool specific content. Probably we should roll up the "Best practices" section?

@travm
Copy link
Contributor

travm commented Dec 27, 2013

@addyosmani Sounds great! Let's create the folder/file structure for the chapters and the sections and how they relate, just to be sure we wont have any conflicts as users begin writing content. Should each chapter and section have it's own separated .md file or will we be adding information to a shared .md file? Should we separate each chapter inside of its own folder? I'm not sure what would be best for everyone contributing and how this would affect the build that has been setup.

@rowoot I think you're right. Unless we can identify specific cases where we need a Best Practices section, I think we could probably roll that up until we absolutely need it. We may need to check with the authors for the other tools to ensure those tools don't need a separate Best Practices section. It may be best to leave it as an optional section as needed, where the other sections we've outlined should be consistent.

@michealbenedict
Copy link
Contributor

@travm and @addyosmani What are your thoughts on the following structure https://github.com/rowoot/book-of-modern-frontend-tooling/tree/file-structure/chapters

The directory structure might something like this

  • Chapters
    • {tool-name}
    • section-{*}.md

Pros:

  • Easier to maintain and accept PR for specific portions of the content.
  • From a dev perspective, we can be creative on how these markdowns can be exported to specific formats (Eg, grep section-* > single html or generate TOC based on section-*)

Cons:

  • Some files might have less to no content, while some (like the tool specific content) will have loads of content

@addyosmani
Copy link
Member Author

I like the proposed structure. What about assets like images? Should all chapters share the same image directory or should each chapter have its own? Once we have that down I'm happy with us to move forward with the above.

Thanks again!

@travm
Copy link
Contributor

travm commented Dec 27, 2013

I'm leaning a bit toward the single image directory. Unless we decide to put each chapter into it's own folder (with the images and sections as subfolders). @rowoot, what are your thoughts?

@ajoslin
Copy link

ajoslin commented Dec 28, 2013

I think one shared assets directory would be best, because we may re-use some images. We can always prefix images by section/chapter if they are collision-risky.

@michealbenedict
Copy link
Contributor

@travm and @ajoslin based on your input, I have an example layout at #9 (comment). Feedback appreciated.

@sindresorhus
Copy link
Contributor

// @contra

@yocontra
Copy link

Awesome! Let me know if anyone has questions in terms of content - always happy to help out. One thing I think is crucial before diving into code (maybe this belongs in "Why Gulp") is explaining streams briefly. People who do front-end dev will not have prior experience with them so it may seem foreign.

@travm
Copy link
Contributor

travm commented Dec 30, 2013

+1 for the streams introduction. @contra, if you have some time, you could probably explain that much better than I could.

I've started on the code examples for each task. We'll start with what I've listed in the outline above and then we can add to it as we identify other common tasks. Also, It may be a valuable to match all the build tool example tasks and keep them as consistent as possible so readers can easily compare and see which tool fits them best.

@yocontra
Copy link

@travm Check out https://github.com/substack/stream-handbook for good analogies and stuff

@dashed
Copy link

dashed commented Jan 5, 2014

If you need a newbie perspective on streams/gulp, I can give some tips 😄

@travm
Copy link
Contributor

travm commented Jan 5, 2014

I've almost completed the intial gulp docs. I'll submit a PR in the next couple days.

@dashed would you be comfortable working on the breakdown explanation on streams and how they work? If not, I can put something together this week!

@dashed
Copy link

dashed commented Jan 5, 2014

@travm I haven't used streams as much other than in gulp.

I had meant that I could give some info from a newbie perspective -- typically some stuff that usually is passed off as trivial knowledge. But, I'd be happy to provide anything that'd be useful.

Are you going to write some stuff in markdown on GitHub?

@travm
Copy link
Contributor

travm commented Jan 5, 2014

I see! Sorry I misunderstood. I'll have the task code examples/walkthroughs ready in the next couple days. Then I can put together some information on streams and the introduction material.

@dashed
Copy link

dashed commented Jan 6, 2014

Looking forward to it.

@travm
Copy link
Contributor

travm commented Jan 6, 2014

Submitted a PR #23 for the initial gulp task examples (and some other info). That should get us started!

@ghost ghost assigned travm Jan 8, 2014
@addyosmani
Copy link
Member Author

@travm Thanks once again for your awesome start on this back in #24. I was wondering if you might have some time to flesh the chapter out a little more. I'd love to get the current content a little more polished and if time is an issue, we can even just link to existing good content as an interim.

@travm
Copy link
Contributor

travm commented Apr 6, 2014

@addyosmani I'd be happy to. I'm in San Francisco this week on Vacation, but once I get back to my office next week I'll definitely see what I can do to flesh it out.

@travm
Copy link
Contributor

travm commented Apr 21, 2014

Sorry about the delay, I'm going to take a look at this chapter this evening and see where and I add more information and possibly improve what is already there.

@gaboesquivel
Copy link
Contributor

hi guys, my little contrib .. gulp-connect is all you need for server/livereload. You may want to talk about The Gulp.js team working on bringing in a new task system to improve efficiency ( even more ) and it might include some API changes, you can follow the progress here gulpjs/gulp#355 ...

I'm working on an intro post, some good refs there https://github.com/gaboesquivel/gaboesquivel.github.io/blob/source/source/_posts/2014-04-20-introduction-to-gulpjs.markdown

This is useful too https://www.npmjs.org/package/lazypipe

@travm
Copy link
Contributor

travm commented Apr 21, 2014

Thanks! I'll take a look at gulp-connect tonight. I'm not sure if it was around when I initially wrote the live-reload bit. gulp-connect seems much better.

I've been thinking about all the improvements they have been working on - and I've been a bit hesitant to continue writing until they have completed those upgrades (especially if the api will end up changing). I'll do some homework tonight and try to get caught up on what they have planned for the future and keep that in mind as I write new information.

Thanks for the help!

@travm
Copy link
Contributor

travm commented Apr 28, 2014

Working on some updates and replaced the LiveReload solo section with gulp-connect and LiveReload information. Thanks @gaboesquivel, they work much better together!

I noticed the Grunt chapter was organized a bit differently and I am afraid I've overlooked a change to the chapter organization. What is the consensus on how we separate the information to keep it consistent across chapters? What works best once we compile into HTML? For example, is it better to separate each task into a separate file? Multiple tasks to a single file? Let me know!

@addyosmani @sindresorhus

@yocontra
Copy link

@travm I would prefer if blacklisted plugins weren't used anywhere in this. I would blacklist gulp-connect 5 times if I could.

@travm
Copy link
Contributor

travm commented Apr 28, 2014

@contra Thanks so much for catching that and letting me know. I'll rewrite that bit again using the connect module directly.

@sindresorhus
Copy link
Contributor

I noticed the Grunt chapter was organized a bit differently and I am afraid I've overlooked a change to the chapter organization

I don't think we have a defined standard, but we should, and it should be consistent.

For example, is it better to separate each task into a separate file? Multiple tasks to a single file?

Can you elaborate?

@travm
Copy link
Contributor

travm commented May 15, 2014

For example, in the gulp chapter I currently have multiple tasks in a single file (writing-tasks.md). In the Grunt chapter it is a separate file for each task (linter.md, sass.md).

I wasn't sure which was best for when we compiled the data into html or pdf. What are your thoughts?

@sindresorhus
Copy link
Contributor

I think writing-tasks.md has an ok length. I don't think it makes sense to split up every task there.

@travm
Copy link
Contributor

travm commented May 15, 2014

Sounds good! I have some revisions to finish up this evening, and then I'll just create an additional file for more advanced tasks and submit a PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

8 participants