[wp-trac] [WordPress Trac] #43055: Reorganize Core JS / introduce build step

[WordPress Trac]

#43055: Reorganize Core JS / introduce build step
------------------------------+-------------------------
 Reporter:  omarreiss         |       Owner:  (none)
     Type:  enhancement       |      Status:  new
 Priority:  normal            |   Milestone:  5.0
Component:  Build/Test Tools  |     Version:  trunk
 Severity:  normal            |  Resolution:
 Keywords:  dev-feedback      |     Focuses:  javascript
------------------------------+-------------------------

Comment (by omarreiss):

 I figured a summary of all changes would be helpful at this point:

 - Introduces a build step to WordPress core development. WordPress can no
 longer be run from `src`.
 - Reorganizes the folder structure for the JavaScript in `src` to the
 following:
 {{{
 src/js                          | All the JavaScript source.
 ├── _enqueues                   | Any script that ends up being enqueued.
 │   ├── admin                   | Procedural scripts ran in the admin.
 │   ├── deprecated              | All deprecated scripts.
 │   ├── lib                     | All standalone lib scripts.
 │   ├── vendor                  | All 3rd party deps that can't be managed
 with NPM.
 │   └── wp                      | All scripts that assign something to the
 wp namespace.
 │       ├── customize           | Anything under wp.customize.
 │       ├── editor              | Anything under wp.editor.
 │       ├── media               | Anything under wp.media.
 │       ├── utils               | Anything under wp.utils.
 │       └── widgets             | jQuery widgets on the wp namespace.
 └── media                       | The media library.
 }}}
 - Cleans the filenames in `src` from namespace references because the
 folder structure now makes that evident.
 - Dependencies that can be installed with NPM have been removed from `src`
 and are built straight from `node_modules`. This will make it much easier
 to manage and update them.
 - Dependencies that still need to be manually included in WordPress have
 been grouped in `src/js/_enqueues/vendor`. A README was included listing
 the sources of all of those dependencies. This will make it easier to
 manage those as well.
 - Backwards compatibility is ensured by making sure the files are being
 built back to the legacy folder/file scheme in production. A future
 consideration could be made to also reorganize the files in the build.
 - Developers who try to run from `src` will land on a screen in the
 browser which explains to them which steps they need to take. The wording
 of that screen can still be improved. There is a separate ticket for that
 here: https://core.trac.wordpress.org/ticket/43732#ticket
 - Tests also need to load code from the `build` directory. This is because
 most of the tests in WordPress core are in fact integration tests. The
 code tested is not isolated and therefore we need to load the entire
 system in order to test functionality. As we get more modular and isolated
 code in the future, we should also have a way to run actual unit tests
 from `src`.
 - The qunit tests have simply been configured to run from `build`. The
 phpunit rely on local config so we added a check to make sure the built
 code is loaded. If this is not the case, we throw an error which explains
 to the user which config they need to change.
 - Grunt watch has been heavily optimized to ensure fast rebuild times. We
 managed to get rebuilds to be around 1 second by making sure to only
 rebuild what has been touched. The initial build will of course still be
 slow.
 - Grunt patch was updated to support filemappings. This makes it possible
 to apply patches to files that were moved.
 - Drafts for documentation exist in
 https://drive.google.com/open?id=1FDD8QQ5TmydZ62nMzPb8pmiVpUSCnhsv. There
 are 4 documents in total with the following topics:
   - JavaScript code organization and development practices
   - JavaScript modules and Webpack
   - Managing dependencies
   - Setting up your local development environment

 To further improve the development workflow, two more tickets were
 created:
 - [https://core.trac.wordpress.org/ticket/43711#ticket Let's create a
 standard development setup for WordPress core]. This ticket aims to
 simplify the development setup for WordPress to be as close as possible to
 a "download and boot" scenario.
 - [https://core.trac.wordpress.org/ticket/43731#ticket Use Webpack + NPM
 scripts to build all the things]. This ticket aims to unify the building
 process and reduce the complexity and number of different build tools.
 - A third ticket could still be created to also reorganize the CSS in a
 similar fashion as we've now done for the JavaScript.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/43055#comment:63>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform