Page MenuHomePhabricator

Process template: How to transition Gruntfile.js tasks to NPM scripts
Open, LowestPublic

Description

This is a detailed process template for transitioning grunt tasks into npm scripts based on lessons learned from the MMV project. The exact steps might vary between projects.
Purpose: removing Grunt from the build pipeline. The basic steps follow established patterns, the 'fix' and 'install' scripts are new. Feel free to discuss and propose alternatives.

Parent task tracking the individual projects: T246321: [EPIC] Should we transition Gruntfile.js tasks to NPM scripts in some projects?

Basic steps
  • grunt eslint -> npm -s lint:js
    • create .eslintignore (sample)
  • grunt stylelint -> npm -s lint:css
    • create .stylelintignore (sample)
  • grunt banana -> npm -s lint:i18n
  • grunt svgmin -> npm -s run svgmin
    • create .svgminrc.json from Gruntfile.js (sample)
  • npm run build : run scripts test, minify, doc (as applicable)
  • npm test : run lint
  • npm run lint : run all lint steps in chain
  • npm run lint:fix : run all lint steps in chain with --fix argument to fix trivial style errors:
    • npm -s run lint:js -- --fix, etc. Note the extra -- that separates the task argument.
  • npm minify : run svgmin script
Developer productivity

Optional scripts to help set up the dev environment.

  • install:global : install the necessary node_modules globally
  • install:link : symlink the node_modules that must be present locally for eslint to work
  • Add DEVELOPERS.md (sample)
Cleanup devDependencies
  • Uninstall grunt and its plugins, except the mediawiki-specific grunt-banana-checker
  • Update and commit package-lock.json for CI

Uninstall grunt:

npm -s un grunt
npm -s un grunt-eslint
npm -s un grunt-stylelint
npm -s un grunt-svgmin
npm -s i eslint@^6.5.1

Note: even though 'eslint' is pulled by 'eslint-config-wikimedia', it still needs to be installed separately, otherwise it fails to load. The version constraint is the same as in 'eslint-config-wikimedia'.

Update and commit package-lock.json:

npm install [--package-lock-only]

Before commit test:

npm -s ci
npm -s test
Sample package.json
{
	"private": true,
	"scripts": {
		"build"    : "npm -s test  &&  npm -s run doc",
		"test"     : "npm -s run lint",
		"lint"     : "npm -s run lint:js  &&  npm -s run lint:css  &&  npm -s run lint:i18n",
		"lint:fix" : "npm -s run lint:js -- --fix  &&  npm -s run lint:css -- --fix  &&  npm -s run lint:i18n",
		"lint:styles" : "npm -s run lint:css",
		"lint:scripts": "npm -s run lint:js",
		"lint:css" : "stylelint  resources/**/*.{less,css}",
		"lint:js"  : "eslint --cache --max-warnings 0  **/*.{js,json}",
		"lint:i18n": "banana-checker --requireLowerCase=0  i18n/",

		"svgmin"   : "npx  svgo --config=.svgminrc.json  -q -r -f resources/",
		"doc"      : "jsdoc",

		"install:svgmin"  : "npm i -s -g  svgo",
		"install:doc"     : "npm i -s -g  jsdoc",
		"install:global"  : "npm i --link --no-save  eslint-plugin-json@1.4.0  eslint-plugin-no-jquery  eslint-plugin-qunit  stylelint",
		"uninstall:global": "npm un -s -g  eslint  eslint-config-wikimedia  eslint-plugin-json  eslint-plugin-no-jquery  eslint-plugin-qunit  grunt-banana-checker  stylelint  stylelint-config-wikimedia  svgo"
	},
	"devDependencies": {
		"eslint": "6.8.0",
		"eslint-config-wikimedia": "0.15.0",
		"grunt-banana-checker": "0.8.1",
		"stylelint-config-wikimedia": "0.9.0"
	}
}

Note: eslint-config-wikimedia depends on

  • eslint-plugin-json@1.4.0, it hasn't been updated to v2.1.0
  • eslint-plugin-mediawiki@0.1.0, it hasn't been updated to v0.2.1
Previous related tasks

T204176: Decide how to configure ESLint rules and ignores
T204260: Consolidate svgmin config and svg / grunt-svgmin checker
T179195: Replace use of .eslintignore with ignore in Gruntfile.js in all repos, for consistency
T56218: Jenkins: Use node-jscs as checkstyle for javascript coding style

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptFeb 27 2020, 9:38 AM
Demian updated the task description. (Show Details)Feb 27 2020, 9:55 AM
Kizule added a subscriber: Kizule.Feb 27 2020, 10:54 AM

Hi @Demian. Can you please associate at least one active project with this task (via the Add Action...Change Project Tags dropdown)? This will allow others to get notified, or see this task when searching via projects. Thanks.

That feels a bit like a stretch... :)

Demian added a comment.EditedFeb 27 2020, 11:22 PM
In T246326#5922949, @Zoranzoki21 wrote:

Hi @Demian. Can you please associate at least one active project with this task (via the Add Action...Change Project Tags dropdown)? This will allow others to get notified, or see this task when searching via projects. Thanks.

Unfortunately, I'm not familiar with the project names at mediawiki and I'm unaware of a fitting project for this task. Nor do I see myself combing through a list of a few thousand (I guess - #200 is Citoid) projects. I hope someone more familiar with these will give a good hint. Feel free to add a project yourself.

In T246326#5923346, @Aklapper removed project "Developer Productivity":

That feels a bit like a stretch... :)

Kind of it is. It makes me more productive :-D But I don't know what's supposed to go in that project...

Looking at the tasks in that project I still think this might belong there.

Demian updated the task description. (Show Details)Feb 27 2020, 11:30 PM
Demian updated the task description. (Show Details)Feb 28 2020, 5:52 AM
Demian updated the task description. (Show Details)
Demian updated the task description. (Show Details)Feb 29 2020, 9:47 PM
Demian updated the task description. (Show Details)
Demian moved this task from Unsorted to Cleanup on the Technical-Debt board.Feb 29 2020, 10:35 PM
Demian renamed this task from Transition Gruntfile.js tasks to NPM scripts (process template) to Transition Gruntfile.js tasks to NPM scripts).Jun 24 2020, 6:44 PM
Demian renamed this task from Transition Gruntfile.js tasks to NPM scripts) to Process template: How to transition Gruntfile.js tasks to NPM scripts.
Demian removed Demian as the assignee of this task.
Demian triaged this task as Lowest priority.