Improve build tool to make it easier to maintain and more pleasant to use #21777

pvdlg · 2017-01-19T02:05:05Z

Reopened here #21929

Following #20332 I've spent some time trying to improve the build process by switching to npm scripts only. See comment.
My analysis is that npm scripts, while looking incredibly simple in theory, present several constraints and that the problems of the build tool are not necessarly related to the tools but mostly the way tasks are organized and orchestrated.

So I decided to evaluate a solution that would make the build tool simpler to use, easier to maintain, robust and more importantly pleasant to use for developers, while building as much as possible on the existing that works.

It turns out it was not that hard and really fun to do :-), so after a couple hours the evaluation turned something that was almost there. So I decided to polish it, update the doc and propose a PR so anyone can can have a look.
Image speak more than words so this is what I have now:

Here is the improvement that this PR brings.

Easy setup

npm install and that's it.

Simple to use

Only 3 commands for the user/developer:

dist: build JS, CSS and Docs.
test: build JS, CSS, Docs, test and lint.
watch: Start everything to dev efficiently.

Only 4 commands for the maintainer:

prep-release: prepare release.
publish: publish doc on GitHub.
change-version: update version in source files.
update-shrinkwrap: update shrinkwrap dependencies management.

Pleasant to develop with

npm run watch, Open your browser and voila! All changes made in scss, js and docs are automatically reflected in live on the local doc website. See gif above :)

Fast

build runs in 6s (it used to be 24s)
test runs in 20s
watch react to a modification of js, scss or docs files, handle everything
and reload the docs on the browser in about 1s (it used to be up to 10s just for sass + time for Jekyll to process the change)

Easier to maintain

Gruntfile is now 10 line of code and shouldn't have to be modified anymore.
For each task there is a short declarative config file under build/grunt.
Grunt tasks have been reorganized in a more logical way and can be found in build/grunt/aliases.js.
No more custom JS script.
No more Javascript function here and there (like in current Gruntfile.js).
Most of the Javascript code has been eliminated. Only the meaningful configuration remains in build/grunt and build/grunt/aliases.js and is written in a more declarative way than it would in an npm script.

Stable

Most of the individual tasks are the one Bootstrap has been running for a while now, so that limit the risk of regression.
All the Grunt plugins are reliable and well maintained plugins (often more up to date than some npm cli equivalent).

How do I use it?

git clone -b build-rework https://github.com/vanduynslagerp/bootstrap
cd bootstrap
npm install
npm run watch
Open you browser to localhost:9001
Start coding! Each modification is applied within 1s and the doc website is reloaded automatically. Just code and watch the result live.

I understand the Bootstrap team, like many others, seems to desire to move to pure npm scripts. That said, I think I reached a pretty satisfying result, that worth to be evaluated, which is the point of this PR.

houndci-bot · 2017-01-19T02:05:24Z

build/grunt/if.js

+    options: {
+      test() {
+        return typeof process.env.SAUCE_ACCESS_KEY !== 'undefined' && (!process.env.TWBS_TEST || process.env.TWBS_TEST ===
+          'sauce-js') && (process.env.TWBS_DO_SAUCE === undefined || process.env.TWBS_DO_SAUCE !== '0')


Unexpected use of process.env no-process-env
'process' is not defined no-undef

houndci-bot · 2017-01-19T02:05:25Z

build/grunt/if.js

+  'sauce-js': {
+    options: {
+      test() {
+        return typeof process.env.SAUCE_ACCESS_KEY !== 'undefined' && (!process.env.TWBS_TEST || process.env.TWBS_TEST ===


Unexpected use of process.env no-process-env
'process' is not defined no-undef

houndci-bot · 2017-01-19T02:05:25Z

build/grunt/if.js

+    options: {
+      test() {
+        return (!process.env.TWBS_TEST || process.env.TWBS_TEST === 'validate-html') && (process.env.TWBS_DO_VALIDATOR ===
+          undefined || process.env.TWBS_DO_VALIDATOR !== '0')


Unexpected use of process.env no-process-env
'process' is not defined no-undef

houndci-bot · 2017-01-19T02:05:25Z

build/grunt/if.js

+  'validate-html': {
+    options: {
+      test() {
+        return (!process.env.TWBS_TEST || process.env.TWBS_TEST === 'validate-html') && (process.env.TWBS_DO_VALIDATOR ===


'process' is not defined no-undef
Unexpected use of process.env no-process-env

houndci-bot · 2017-01-19T02:05:26Z

build/grunt/if.js

+  core: {
+    options: {
+      test() {
+        return (!process.env.TWBS_TEST || process.env.TWBS_TEST === 'core') && process.env.TRAVIS_REPO_SLUG !==


Unexpected use of process.env no-process-env
'process' is not defined no-undef

houndci-bot · 2017-01-19T02:05:26Z

build/grunt/if.js

@@ -0,0 +1,29 @@
+module.exports = {


'module' is not defined no-undef

houndci-bot · 2017-01-19T02:05:27Z

build/grunt/htmlhint.js

@@ -0,0 +1,8 @@
+module.exports = {


'module' is not defined no-undef

houndci-bot · 2017-01-19T02:05:27Z

build/grunt/htmllint.js

@@ -0,0 +1,28 @@
+module.exports = {


'module' is not defined no-undef

houndci-bot · 2017-01-19T02:05:27Z

build/grunt/connect.js

@@ -0,0 +1,14 @@
+module.exports = {


'module' is not defined no-undef

houndci-bot · 2017-01-19T02:05:28Z

build/grunt/eslint.js

@@ -0,0 +1,20 @@
+module.exports = {


'module' is not defined no-undef

houndci-bot · 2017-01-19T02:05:28Z

build/grunt/cssmin.js

@@ -0,0 +1,27 @@
+module.exports = {


'module' is not defined no-undef

houndci-bot · 2017-01-19T02:05:28Z

build/grunt/copy.js

@@ -0,0 +1,18 @@
+module.exports = {


'module' is not defined no-undef

houndci-bot · 2017-01-19T02:05:29Z

build/grunt/watch.js

@@ -0,0 +1,24 @@
+module.exports = {


'module' is not defined no-undef

houndci-bot · 2017-01-19T02:05:29Z

build/grunt/concurrent.js

@@ -0,0 +1,45 @@
+module.exports = {


'module' is not defined no-undef

houndci-bot · 2017-01-19T02:05:29Z

build/grunt/concat.js

@@ -0,0 +1,24 @@
+module.exports = {


'module' is not defined no-undef

houndci-bot · 2017-01-19T02:05:30Z

build/grunt/uglify.js

@@ -0,0 +1,26 @@
+module.exports = {


'module' is not defined no-undef

houndci-bot · 2017-01-19T03:39:34Z

build/utils/travisTestEnv.js

+    },
+    // Skip Sauce on Travis when [skip sauce] is in the commit message
+    isDoSauceJs() {
+      return this.isSauceJs() && isUndefOrNonZero(process.env.TWBS_DO_SAUCE)


Unexpected use of process.env no-process-env
'process' is not defined no-undef

houndci-bot · 2017-01-19T03:39:35Z

build/utils/travisTestEnv.js

+    // Only run Sauce Labs tests if there's a Sauce access key
+    // and skip Sauce if running a different subset of the test suite
+    isSauceJs() {
+      return typeof process.env.SAUCE_ACCESS_KEY !== 'undefined' && runSubset('sauce-js-unit')


Unexpected use of process.env no-process-env
'process' is not defined no-undef

houndci-bot · 2017-01-19T03:39:35Z

build/utils/travisTestEnv.js

+    // Skip HTML validation if running a different subset of the test suite
+    // or [skip validator] is in the commit message
+    isValidateHtml() {
+      return runSubset('validate-html') && isUndefOrNonZero(process.env.TWBS_DO_VALIDATOR)


Unexpected use of process.env no-process-env
'process' is not defined no-undef

houndci-bot · 2017-01-19T03:39:35Z

build/utils/travisTestEnv.js

+    // Skip core tests if running a different subset
+    // of the test suite or if this is a Savage build
+    isCore() {
+      return runSubset('core') && process.env.TRAVIS_REPO_SLUG !== 'twbs-savage/bootstrap'


Unexpected use of process.env no-process-env
'process' is not defined no-undef

houndci-bot · 2017-01-19T03:39:35Z

build/utils/travisTestEnv.js

+module.exports = function () {
+
+  function runSubset(subset) {
+    return !process.env.TWBS_TEST || process.env.TWBS_TEST === subset


Unexpected use of process.env no-process-env
'process' is not defined no-undef

houndci-bot · 2017-01-19T03:39:36Z

build/utils/travisTestEnv.js

@@ -0,0 +1,32 @@
+module.exports = function () {


'module' is not defined no-undef

houndci-bot · 2017-01-19T03:39:37Z

Gruntfile.js

-          branch: 'gh-pages'
-        }
+  require('time-grunt')(grunt)
+  require('load-grunt-config')(grunt, {


Unexpected require() global-require
'require' is not defined no-undef

houndci-bot · 2017-01-19T03:39:37Z

Gruntfile.js

-          remote: '[email protected]:twbs/derpstrap.git',
-          branch: 'gh-pages'
-        }
+  require('time-grunt')(grunt)


Unexpected require() global-require
'require' is not defined no-undef

…of the number of line inserted)

# Conflicts: # package.json

bardiharborow · 2017-01-22T08:21:56Z

This is interesting, but a heads-up that I can't guarantee we'll use this.

pvdlg · 2017-01-22T16:08:00Z

@bardiharborow that's alright. I continue to improve it whenever I see something because I use it when I work on Bootstrap. The gain in comfort and productivity is really appreciable.
So even if Bootstrap decide to not go that way, it's not lost as I would have used it for a while.

Btw, let me know if you want me to improve/change something that would help this build tool to be adopted.

# Conflicts: # Gruntfile.js # package.json

# Conflicts: # Gruntfile.js # docs/.htmllintrc # package.json

# Conflicts: # package.json

twbs-rorschach · 2017-02-06T23:28:13Z

Hi @vanduynslagerp!

Thanks for wanting to contribute to Bootstrap by sending this pull request!
Unfortunately, your pull request seems to have some problems:

Changes must be made to the original Sass or Less source code file(s), not just the compiled CSS file(s).

You'll need to fix these mistakes and revise your pull request before we can proceed further.
Once you've fixed these problems, you can either ask the maintainers to re-open this pull request, or you can create a new pull request.
Thanks!

(Please note that this is a fully automated comment.)

pvdlg added 5 commits January 18, 2017 15:07

Merge branch 'fix-scrollspy-test-markup' into build-rework

744d551

Full build tool rework

930bac8

Merge branch 'twbs/v4-dev' into build-rework

23d5422

Remove build task, fix Unit test

89a2273

Remove path.json for simplification

56cddad