WP Make has been a very useful tool, but has suffered many small problems over the last several years. To that end, WP Make has been re-imagined in a way to try and deal with many of the pain points it has had to-date.
WP Make has been in a sub-one-point-oh state since its inception. This was intentional, as it was intended originally to be a port of the original grunt-init plugin and theme scripts, moved over to Yeoman in as quick a way possible. With 1.0, we will take what we learned from this hodgepodge of scripts and apply it to creating a smooth, flexible, and maintainable generator to help us bootstrap our work more quickly.
The heart of the 1.0 changes is a major architecture shift. Where before WP Make was the most basic of Yeoman generators, now it will come into it's own with an architecture that makes input and output much more declarative and flexible.
WP Make 1.0 will have three lifecycle stages:
- Prompting
- Mutation
- Output
This makes a lot of sense considering this is the flow of pretty much every Yeoman generator out there. The major difference is that WP Make will begin using a declarative lifecycle object.
{
prompts: [],
tree: {}
}The prompts are an array of questions that are asked of the user. These generally follow the standard Yeoman Inquirer system for asking questions. However in addition to all of the standard Inquirer keys, each inquiry object also supports a tree object key, allowing for declarative conditional questioning.
Imagine you have asked a user if they would like to use Sass. If they have said yes, Autoprefixer gets included automatically as part of that workflow. However, because the user has said no to Sass, you now need to ask if they would still like to use Autoprefixer. You could write that conditional like this:
{
type: 'confirm',
name: 'sass',
message: 'Use Sass?',
default: true,
tree: {
false: [{
type: 'confirm',
name: 'autoprefixer',
message: 'Use Autoprefixer?',
default: true
}]
}
}This tree system allows for a very complex set of questions to be asked in a very straight forward fashion.
The tree key in the lifecycle object defines what files will be output and in what folders they will go. Think of this as a simplified JS object representation of the filesystem.
in each level of the tree object the user can specify different types of files to output:
{
prompts: [],
tree: {
json: {},
templates: {},
copies: {},
modules: {}
tree: {}
}
}Every file type then contains object key-value pairs that are output as filename: contents. The contents vary depending on the type of output. JSON output contains an standard JS object which will get strigified. The templates contain the location of the template file to use, which will get passed the answers from the prompts. Copies are direct copies of a file, useful for static files. Modules are node modules, containing an AST representation of the JS code.
Notice that the main tree object contains another tree object. This allows you to next file output. Keys in the tree object correspond with folder names, while their contents is defined using the output object described above. Each tree can contain it's own subtree.
In between the prompting phase and the output phase is the Mutation phase. The data from the prompting is available for mutation. This allows generator authors to intuit information from what was collected, modify parts of the output tree based on answers, or generally make any needed changes to the collected data or planned output. This is the phase where the pile of answers becomes the specifically requested project setup.
Each generator will have an initialization method that will return the lifecycle object with the needed prompts and base output tree. Other functions in the generator will then fire during the Mutation phase, allowing the generator to modify the output object based on the collected input.
At that point, the framework takes over walking the tree object and outputting each file and folder specified.
Afterwards the framework attempts to run npm install and composer install for the user to get the setup fully bootstrapped.
It is conceivable that a simple generator could be 100% declarative. A few questions in the prompting phase that will modify specific templates output, but without the need to declare extra functions for the mutation phase.
While the lifecycle itself generally takes care of the input and output based on the lifecycle object of the invoked generator, version 1 of WP Make provides some very useful utilities, used both internally to manage lifecycle, or during the mutation phase to assist final output tree creation.
Utilities for walking the complex output tree are provided so that different depths of the tree can be accessed by specifying the final file-path to get access to that section of the tree object.
Other utilities are available as well in an attempt to make generator authoring as painless as possible.
In particular the helpers for output template files support looking first in the sub-generator for the template and then falling back to a set of global templates that can be shared across all sub-generators. This strikes a balance between shared templates, and full customizability by sub-generators.
WP Make has always worked using sub-generators. The main generator has always output help text advising users to invoke a sub-generator to get started.
This will be made dynamic in Version 1, automatically working out the available sub-generators.
WP Make embraces ES2015 in version 1. This helps simplify the source code for easier reading and understanding.
WP Make has worked with JSHint to date, but with Version one it is making the switch to the far more flexible and useful ES Lint.
WP Make has been largely un-tested to date. The architectural updates make WP Make far more testable due to the modularized organization. The goal is to to fully test WP Make in version 1, or at the very least grow coverage considerably.
Testing will be conducted with Mocha and Chai, and the entire set up will be integrated with Travis CI and well as Code Climate to help avoid future bugs and keep up quality.
WP Make version 1 will feature a brand new extension system. The recent Profiles system in WP Make will be maintained as well, but extensions will allow fully third party code to modify and add the WP Makes behavior and capabilities.
The extension system will work based on the Extendable Yeoman package that was created recently for exactly this purpose.
Events will be added to WP Make at the following places for extensions to hook in:
- Startup
- Allows functions to run any startup needs, such as version checkes, etc.
- Before Prompting
- allows for extensions to modify the questions that are asked
- After Prompting
- allows extensions to mutate answers or the output tree before the main generator gets to see the data
- Before output
- allows extensions to mutate the data object or output tree after the main generator has worked on it
- Post output
- allows extensions to run any additional scripts or changes to things before the install runs
- Shutdown
- allows extensions to do things right before Yeoman exits
- Main generator
- allows extensions to hook in to the main generator help text before output and add to it if needed.
In addition to these events, WP Make will export it's base object as the default export, allowing it to be consumed by extensions to create dynamic Slash Generator (sub-generators that do not exist in the main generator module) while taking full advantage of the WP Make architecture and lifecycle.
WP Make has previously contained sub-generators for bootstrapping a plugin, a theme, a child them, and a WP Composer Library. The latter of these does not feel appropriate for WP Make core and will be migrated into an extension as a slash generator. The other three sub-generators will continue as the core set of functionality provided out of the box by WP Make.
Many improvements will be made to the three core sub-generator project.
We will shift those projects to ES Lint with JS testing in Mocha as well. We will also add full JSCS support. Code will still compile using Grunt, but it will run through WebPack to compile ES2015 modules.
Bower will be deprecated and removed from WP Make output.
The includes/functions folder will be removed as it's unneeded complexity. The contents will be migrated to live directly in includes.
The composer.lock file will no longer be in the .gitignore file.
Many readme files will be removed. They were good documentation in the initial version, but end up cluttering projects. Some consideration will need to go into how we will track empty-by-default folders because git tracks files, not folders directly.
Grunt will transition to using the load-grunt-config module, which allows for a completely modularized approach to task management. This is similar to the current modularized grunt behavior, but it takes it one step further.
No major changes will be made to CSS or CSS processing at this time. We will continue to support Sass by default, offering a no-sass option, as well as an autoprefixer option.
No project can survive without documentation. Since there are a lot of changes coming, it will be imperative that we document them and allow all of our users to get the most out of WP Make.
At this point the documentation will be manually created, however at some point in the future it would be good to set up a JSDoc parsed site for WP Make.
- Moving the modules files type in the output tree over to something like AST to mark it as more complex JS. Then adding basic function support to the JSON output type through the use of Object Stringify.
- Remove the child-theme sub-generator migrating it into an extension that modifies the theme generator output when a flag is passed.