Currently all of Gulp tasks that produce the final www.wikipedia.org page are located in a single Gulpfile.js file in the root of the portals repo. This makes the build process difficult to understand and maintain. Splitting the Gulp tasks into separate files would help contributors understand what each function is responsible for, and eventually, may make it easier to refactor and replace part of the build process in the future.
Splitting a Gulpfile is also recommended in the Gulp.js documentation:
https://gulpjs.com/docs/en/getting-started/javascript-and-gulpfiles#splitting-a-gulpfile
All Gulp.js related code should be placed in folder called "gulpfile.js"
The first piece of work required for this refactor is to create a folder called /gulpfile.js/ at the root of the repo, and move the /gulpfile.js file into /gulpfile.js/index.js as is recommended by the Gulp.js documentation. https://gulpjs.com/docs/en/getting-started/javascript-and-gulpfiles#splitting-a-gulpfile
Gulp task functions should be split into separate files
Currently most Gulp tasks are defined as functions, and the right below the function, a gulp.task() call registers the function as a Gulp task. This task involves moving the functions into separate files, but keeping the gulp.task definitions in /gulpfile.js/index.js (changing export names, as recommended by the Gulp.js documentation, can be done in a followup task).
Example of a current Gulp task in gulpfile.js:
function compileHandlebars() { requirePortalParam(); return gulp.src( getConfig().hb.src ) .pipe( plugins.compileHandlebars( getConfig().hb.templateData, getConfig().hb.options ) ) .pipe( plugins.rename( 'index.html' ) ) .pipe( gulp.dest( getBaseDir() ) ); } gulp.task( 'compile-handlebars', compileHandlebars );
Becomes a separate file called gulpfile.js/handlebars.js with the necessary functions and a module export
function compileHandlebars() { requirePortalParam(); return gulp.src( getConfig().hb.src ) .pipe( plugins.compileHandlebars( getConfig().hb.templateData, getConfig().hb.options ) ) .pipe( plugins.rename( 'index.html' ) ) .pipe( gulp.dest( getBaseDir() ) ); } exports.compileHandlebars = compileHandlebars;
And then in gulpfile.js/index.js:
const { compileHandlebars } = require('./handelbars.js'); gulp.task( 'compile-handlebars', compileHandlebars );
NOTES:
- This work should be split across multiple patches. Each new file created can be a separate patch.
- Most tasks share common dependancy functions like requirePortalParam() and getConfig(). These will have to be separated first, and then imported by each individual file that requires their usage.
- Many tasks require plugins that are loaded via plugins = gulpLoadPlugins() . This dependancy should be carried over into the separate files as well.
- The changes can be tested by running npm run build-all-portals and viewing the contents of the prod folder. That task should continue to run successfully.
New file structure
A folder called /gulpfile.js should be created at the root of the repo and the existing gulp file should be moved to /gulpfile.js/index.js. The functions inside index.js can be split into different files in the following way:
New files to be created in the /gulpfile.js/ folder
help.js
The first task, help() can be moved into its own file.
https://gerrit.wikimedia.org/r/plugins/gitiles/wikimedia/portals/+/refs/heads/master/gulpfile.js#23,
config.js
https://gerrit.wikimedia.org/r/plugins/gitiles/wikimedia/portals/+/refs/heads/master/gulpfile.js#52
- requirePortalParam()
- getBaseDir()
- getProdDir()
- getConfig
handlebars.js
https://gerrit.wikimedia.org/r/plugins/gitiles/wikimedia/portals/+/refs/heads/master/gulpfile.js#146
- compileHandlebars()
postcss.js
https://gerrit.wikimedia.org/r/plugins/gitiles/wikimedia/portals/+/refs/heads/master/gulpfile.js#163
- postCSS()
- validatePostCSS()
- lintCSS()
prod.js
- inlineAssets()
- cleanProdJS()
- copyTranslationFiles()
- concatMinifyJS()
- minifyHTML()
- copyImages()
- createProdSymlink()
javascript.js
- lintJS()
stats.js
- updateStats()
meta.js
- fetchMeta()
sprites.js
- cleanSprites()
- createSvgSprite()
scap-urls.js
- updateURLsToPurge()
dev.js
- watch()
Note that these refactors can be split into separate patches. After this clean-up, the file in gulpfile.js/index.js should just contain imports and gulp.task definitions.