[wp-trac] [WordPress Trac] #51966: npm/grunt watch/build task names are inconsistent and unintuitive

[WordPress Trac]

#51966: npm/grunt watch/build task names are inconsistent and unintuitive
------------------------------+-----------------------------
 Reporter:  iandunn           |      Owner:  (none)
     Type:  enhancement       |     Status:  new
 Priority:  normal            |  Milestone:  Awaiting Review
Component:  Build/Test Tools  |    Version:  5.1
 Severity:  normal            |   Keywords:
  Focuses:  javascript, docs  |
------------------------------+-----------------------------
 #43055 / #44492 made a lot of changes to the typical dev workflow, and I
 often have trouble getting the right watch or build command going, because
 they don't seem intuitive or consistent to me.

 The `dev` flag feels vague, and doesn't describe what it actually does
 (builds into `src/` instead of `build/`), the `npm` commands aren't always
 internally consistent, or consistent w/ the corresponding `grunt`
 commands. They're also syntax differences between `npm` and `grunt` which
 need to be memorized.

 Some examples:

 * There's `npm run build` and `npm run build:dev`, but the corresponding
 commands are `npm run watch` and `npm run dev`, instead of `npm run
 watch:dev`.
 * `npm run build` wraps `grunt build`, but `npm run dev` wraps `grunt
 watch --dev`; there is no corresponding `grunt dev` task.
 * running `npm run watch --dev` will run `grunt watch` (into `build/`)
 instead of `grunt watch --dev` (into `src/`). That's because `npm` uses
 `-- --` to pass a flag to the proxied command, but grunt uses `--`.


 The commands aren't clearly documented in the Handbook or readme file, so
 I have to read the `package.json` or `Gruntfile.js`, and try to memorize
 the inconsistencies.

 ==== Ideas

 I think it'd help to:

 * Add clear documentation about the purpose of the `src/` and `build/`
 folders, the pros/cons of running from each, and the commands needed for
 each scenario.
 * Rename the commands/flags to be self-documenting and consistent.

 I'll open a PR with a rough implementation of those as a starting point.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/51966>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform