Use CSS partials and include a grunt task

[necolas]

Breaking up the CSS into different files has several benefits:

• Normalize.css can be included as a drop-in. This makes it easier to
  apply upstream changes and track which version of normalize.css is
  included in HTML5 Boilerplate.
• Easier for people to remove or replace parts of the CSS. For example,
  if someone would rather use their own custom reset, they can pull out
  normalize.css without any trouble.
• Encourages people to use multiple files in development. You wouldn't
  (or shouldn't) write all your JavaScript in one huge file. The same
  goes for CSS.
• A step towards making it easier to integrate HTML5 Boilerplate into
  larger application frameworks.

Included as part of this change is the addition of a package.json and
simple grunt.js file. The package.json file allows us to group various
pieces of information about the project, such as the version number. It
will also act as the place to list any Node package dependencies, such
as the H5BP node-build-script.

The grunt.js file sets up grunt 'concat' and 'watch' task to combine the
separate CSS files into a single main file. People can either edit the
main file directly or continue to use the grunt task during development.
This relies on a user of the boilerplate having Node.js, npm, and grunt
installed. These are technologies that can be used on any OS and are
particularly well suited for use by Front End developers.

Ref #1132

[necolas]

Amended commit to integrate this and @mathiasbynens's feedback. Any other general thoughts or comments on the approach?

[mathiasbynens]

I’m not a big fan of dependencies in general, but as Grunt works pretty much everywhere (and is amazingly awesome), I’m okay with it in this case.

+1 to splitting up the CSS like this. Much cleaner. I just hope it won’t confuse people too much, or cause them to reference more than once CSS file in the HTML.

[necolas]

It's almost a dev dependency as there is no requirement to use grunt from end users. We'll have to make it as clear as possible what is going on. It does pain me a little to have more files added to the root, and soon a metro icon too. Maybe one day we'll put the touch icons in the img directory :P

Might put a tweet out and get some eyeballs on this stuff so we can see what needs to be clarified.

[Kroc]

Why not put the dev stuff in a dev folder? build tools, separate CSS files etc, and get the build script to output to /css (the project's CSS, not H5BP's dev CSS) — i.e. separate what is H5BP's tools and what is space for the user's project being built using H5BP

[necolas]

Hmmm. I think the separate CSS files and build step is the way to go during normal project development, and I'd be ok with encouraging it. But as you mentioned in a previous discussion, doing it this way doesn't exclude people who would rather stick to the single-file-no-dependencies approach.

[drublic]

Nicolas, this is great work!
This moves the project forward a lot I think as it makes it even easier to integrate HTML5 Boilerplate in larger projects as you stated.

Two things I wanted to mention:

1. We could define a default-task for grunt:

 grunt.registerTask('default', 'concat');

Running $ grunt will not fail anymore with this included.

2. The version number could be something like 4.0.0pre because I think we are not at the 3.0.2 stage anymore. The project has evolved and is not far from being a new stable release.

All in all it looks clean and well done. I like the watch-task and the fact that you prefixed partials with an underscore. Pretty clean.

[Kroc]

I’m okay with these changes, but I participate here to be a word of warning, that if a user has to install anything to use H5BP then you have failed. It is my right to choose my development tools and not to burden others with them either, no matter how rad I think they are. :)

[necolas]

@drublic Thanks, good points and good spot on the missing default task. Updated.

@Kroc That is something we've been acutely aware of over the years, and is still important to the project. Fortunately, this change wouldn't require people to install anything extra.

[devinfd]

I'm a fan of this idea however I think there should still be a simplified version of H5BP for the average user. Not everybody understands grunt and if H5BP is meant to be a simple out-of-the-box tool then we don't want to discourage other developers.

[necolas]

You wouldn't need grunt.

[shama]

+1 for this.

[shama]

You can exclude compiled files from the repo and still provide a way to download (even customize) without dependencies. All done in the browser. We do this on jmpress.js: http://shama.github.com/jmpress.js/docs/#builder /cc @sokra

We use grunt and have a grunt task for it: https://github.com/sokra/grunt-webpack

[necolas]

The problem with excluding the compiled file (in this case), is that it then requires end users to install node.js and run the grunt task to have the boilerplate work out-of-the-box if they got the code from anywhere other than an online builder like Initializr.

[nimbupani]

I think half of H5BP users are those who have absolutely no clue on build tools. Personally, this is like the best idea ever, but I am just concerned that this might alienate such users even further?

Perhaps there should be a way for them to exclude these files from being downloaded on Initializr?

cc: @verekia

[shama]

Also I would like to point out that jQuery and jQuery UI both use grunt.

[AD7six]

Howdy

I'm a little concerned with some aspects of this pull request and put my opinion here to have it out there. But it's just that, an opinion.

Splitting css files is good

No brainer really.

The existing css file has always been a little hard to integrate with other projects - and the reason is simply because the rules are order-sensitive and the project-specific rules go in the middle. For this reason I'm quite happy to see multiple css files in the repository.

Creating multiple css files makes it easier to maintain the files, and generally allows more developer freedom.

Duplication in a repository is bad

These changes put each css rule in 2 files. It doesn't matter how big a comment you put in main.css - there will still be:

1. pull requests editing main.css
2. developers/teams managing to lose changes as one dev edits main.css and others edit the component files

Don't add built-assets to the repository

Any file that you can derive from something else in the repository doesn't belong in the repository. As such I echo @shama's comment that they don't /have/ to be in the repository - they could be added as part of a download process, and that's how jquery and jquery-ui do it.

If you want to ensure that the download from github works without problems why not make main.css:

/* Appropriate Description */
@import url( _normalize.css)
@import url( _base.css)
@import url( _helpers.css)
@import url( _media.css)

Bearing in mind that the file should be only used in that form in development and purely to ensure it works.

In development multiple files is easier to work with

if you have

<!-- css concatenated and minified via build script -->
<link rel="stylesheet" href="css/_normalize.css">
<link rel="stylesheet" href="css/_base.css">
<link rel="stylesheet" href="css/_helpers.css">
<link rel="stylesheet" href="css/_media.css">
<!-- css scripts -->

In development, editing your css files is potentially a lot easier, and the benefits of pre-processing the css files are preserved without compromising on committing all css rules in 2 places.

Best practices not tools

And finally - I know grunt is a great tool, but I have the perception that this project is becoming less about markup and coding practices and more about which tools to use.

[chrisjaure]

Yay, I've been breaking the css up manually to use with my own css packager. Nice to know I won't have to be doing that anymore.

[necolas]

Don't add built-assets to the repository

Ideally, yes.

they could be added as part of a download process, and that's how jquery and jquery-ui do it.

Those projects never set out to be used by cloning the github repo.

If you want to ensure that the download from github works without problems why not [use @import].

Because there is no way we would be able to ensure that people didn't put things in production using @import, and we'd get endless issues about how it's terrible.

In development multiple files is easier to work with

Agreed. The problem with wrapping build script comments around the files is that most people will never use the build script and they'll end up with multiple HTTP requests. Having said that, including multiple link elements in the HTML wouldn't be the end of the world, and I'd rather do that than use @import.

I have the perception that this project is becoming less about markup and coding practices and more about which tools to use.

What gives you that perception? The commit log doesn't justify it. Besides, this project was never just about HTML and coding practices, it has always been to about helping people to "build fast, robust, adaptable, and future-proof websites".

This is one pull request that is looking to encourage a good practice and be improved through feedback. The current commit avoids imposing hard tooling requirements, and the project currently has fewer dependencies and bundled tools than it did back when it had the ant build script and qunit included. But if one day adding a basic tooling dependency is what keeps this project useful and relevant, then so be it.

[sokra]

I want to propose another option, which supports build tools and cloning to repo.

Make two parallel branches:

• One without compiled files, files seperated, maybe development friendly files (@import)
• One with compiled files.

Commits should be applied to the first branch (there are not duplicate things, so it do not make your history noisy)

On releases a merge commit is applied to the second one, including all changes in the first branch (thought the merge) and a compile step.

Your users can clone the second brach easily as it includes the compiled files and the user need no build tool. The first branch acts nicely for the developer with the points @AD7six made.

[devinfd]

I agree with the above comments about "user firiendly-ness" for all users.
I personally do break my CSS files up into more maintainable bits and then build them together for production, so I think this is a great idea.

As with many people, I learned a lot from this project. My only concern with the proposed idea is that new developers will become alienated.

Two branches, "Advanced" and "Not-so-advanced" sounds like a fair compromise for all users. Though, in fairness, I will admit that maintaining two main branches can also create a challenge.

[sokra]

yeah it's a bit of a challenge. But the challenge is on developer side not on user side. ;)

[verekia]

@nimbupani Yep, I can definitely have an option on Initializr (and on your Customize Boilerplate builder) to choose between the dev and the prod version of the CSS. Just like there is a minified or development jQuery option.

[vendruscolo]

IMHO we should encourage users to do-the-right-thing™.
We all agree that splitting the CSS into smaller files is good because the project becomes easier to maintan, and that concatenating files reduces the number of HTTP requests and the site becomes faster.

So, to do this and teach it to the users I would:

• Split the files and add the Grunt task (will teach the good parts);
• Edit the HTML to point to the builded CSS (which won't be in the repo, and will fix the problem of downloading/cloning the Git repo (because you get a 404));
• Edit the README telling about Grunt and why is this good and also pointing them to the H5BP site where they can download the Boilerplate already builded and ready to use (just as jQuery does).

What do you think?

[Kroc]

And what if I don't think grunt is the RightThing^tm? Never force
people to install software just because you think it's good for them.
I have the right to develop the next world-dominating web service on
an Amiga if I so desire, it's all just text.

Solution IMO is to put all the build stuff in a "dev" folder and
include the combined file (in /css) and the separate CSS files (in
/dev). The downloader is not hindered in any way and what method they
use is up to a. their skill level and b. the type of project they're
building -- not every site needs a build system because not all of us
are making walled gardens, we're making documents. :)

--Kroc

----- Original Message -----
From: "Alessandro Vendruscolo"
To:"Kroc Camen"
Cc:
Sent:Tue, 10 Jul 2012 00:04:53 -0700
Subject:Re: [html5-boilerplate] Use CSS partials and include a grunt
task (#1140)

IMHO we should encourage users to do-the-right-thing™.
We all agree that splitting the CSS into smaller files is good
because the project becomes easier to maintan, and that concatenating
files reduces the number of HTTP requests and the site becomes faster.

So, to do this and teach it to the users I would:

• Split the files and add the Grunt task (will teach the good
  parts);

• Edit the HTML to point to the builded CSS (which won't be in the
  repo, and will fix the problem of downloading/cloning the Git repo
  (because you get a 404));

• Edit the README telling about Grunt and why is this good and also
  pointing them to the H5BP site where they can download the Boilerplate
  already builded and ready to use (just as jQuery does).

  What do you think?

  ---

  Reply to this email directly or view it on GitHub:
  Use CSS partials and include a grunt task #1140 (comment)
  [1]

Links:

[1]
#1140 (comment)

[vendruscolo]

Maybe I didn't explain well in my previous comment:

• The repo should have the task and the files splitted;
• The user should be able to clone the repo and should understand how to build it, reading the README (this is the latest unstable version);
• The user should be able to download the development version of the project from the project site (this is the latest stable version, with the grunt task and the CSS files splitted);
• The user should be able to download the production version of the project from the project site (this is the latest stable version already builded, without the grunt task and with the CSS already concatenated — this is the current situation).

So on the site we'll have two version: the development and the production version.
In this way, if the user doesn't like grunt or doesn't want to install it, he can use the production version (which is just as it is now – one CSS file that holds everything).

[Kroc]

Here’s an idea: What if H5BP was a sub-folder of the build system?

That is, the user can download either the outer folder (the build system, and H5BP within) or the inner folder (just H5BP).

This would also work well with git; H5BP would just be a sub-module of the build system.

[varemenos]

i like @Kroc approach

[drublic]

Separate Branches

Separating the development from the production is not what I think is best for the user. We don't want the user to choose what is the right thing for him because he/she might not know. It is confusing to have two branches that look kinda the same but you have to decide which one to take. And what should be the default branch, dev or prod? I'd rather go with dev, but if people download that and get a 404 for the styles.css file they get confused and confusion is not what we should aim for IMO.
Besides that we already have two different versions of HTML5 BP available: stripped and the current default with annotations (discussed in #1048).

A dev-Folder

@Kroc's first solution is something that I like: include a dev folder into the project which has all the partials. They are not part of the css folder anymore which then does not confuse users in a team about which files to edit. Everyone who is willing to use Grunt for their project will be able to figure out which files to edit.
This leaves us with the problem of Pull Requests editing the main.css file instead of the partials which is very likely. Well… I think this is a burden we can take. Even if users submit PR's for main.css we will point them to the partials. I don't think that this will be a hugh problem as there are not that many pull requests popping up.

HTML5 BP as a Submodule of a Build-System

The second proposal by @Kroc is not a good way for me. Having a submodule in the build-system is another impediment for users that want to use the build-system. Besides that we have to maintain partials in the build-repo rather than in the HTML5 BP's repo. This should not be a default and is not sensible in my opinion.

Tooling

That said I wanted to point out that sometimes we refuse to include small tools that could help improve the workflow of some users and we try to keep the repo tight. With adding Grunt we will add some "cluster" to the repo.
In this case I prefer having a bit of tooling in here and suggest users to use it because it adds real value and moves the project forward.
In general I'm in favor of adding little helpers and tools to the project to improve user's workflow even though it does not always keep the project to a minimum.

[necolas]

OK, since this has spawned a whole new set of problems/proposals, it should probably be abandoned.

However, I'd like to disentangle normalize.css from the html5 boilerplate CSS, so I'm thinking that we go for a much simpler approach for now and just have 2 CSS files referenced in the HTML - normalize.css and main.css. It would mirror the separation we imply in the JS files we bundle, avoid the issues surrounding committing compiled files and worries around dependencies at this stage, but still deliver some of the other benefits previously discussed.

[necolas]

Closing. Anyone interested still has time to review #1160. Thanks for all the great feedback and alternative ideas.