Workflows - dotherightthing/wpdtrt-plugin-boilerplate GitHub Wiki

Summary

The DTRT WordPress Plugin Boilerplate system uses Yeoman, Gulp and Travis build systems. Common workflows are outlined below.

Status

Stable @ 1.6.1
TODO: explain the functionality of the NPM scripts (see #177)

Usage

System requirements

Create a new plugin

Install and run the DTRT WordPress Plugin Boilerplate Generator (Yeoman).

Prepare boilerplate or plugin for development

Install (any new) PHP dependencies (Composer)
Install PHP and front-end dependencies which don't have composer.json files (Yarn)
Lint SCSS, PHP and JavaScript code
Generate PHP and JavaScript documentation
Compile SCSS into CSS
Transpile ES6 JS into ES5

$ yarn run build

Add new features to the boilerplate

The boilerplate contains functionality which is accessed by generating and configuring a plugin.

Although each plugin has its own focus, every plugin must use the same structure and conventions in order to be compatible with each version of the boilerplate.

Therefore, when updating the boilerplate, it will usually be necessary to update the Yeoman plugin generator as well.

The resulting releases of both provide a detailed list of changes which must be made to each existing generated plugin, before it can access the new features added to the current version of the boilerplate.

Release 0.7.25

Load PHPUnit config from boilerplate (0.7.22)

Use WPUnit install script from boilerplate (0.7.22)

Refactor JS to generate meaningful JSDoc output (0.7.22)

Include repository sources in child plugin (0.7.22)

Simplify inclusion of boilerplate dev dependencies (0.7.22)

Install WordPress plugin dependencies using WordPress Packagist (0.7.22)

Don't suggest other packages during composer install/update (0.7.22)

Fix Slack notification (0.7.22)

ES6 & JSDoc fixes (0.7.22)

Specify at least current version of boilerplate dependency (0.7.23)

Increase verbosity of composer install messages (0.7.25)

Expose GH_TOKEN to Composer via both Travis and Yeoman (0.7.25)

This complexity is hidden from plugin releases, which need only reference the release versions:

Release 0.1.8

Update wpdtrt-plugin-boilerplate to 1.4.38

Sync with generator-wpdtrt-plugin-boilerplate 0.7.25

Note: While Travis CI can also verify compatibility between the plugin and boilerplate, it is most efficient to run these tests in the local development environment first. This reduces commit noise and provides a clearer upgrade path for existing generated plugins.

In the generated plugin, replace the boilerplate installed by Composer with a symlink to the local copy:

cd vendor/dotherightthing
rm -r wpdtrt-plugin-boilerplate
ln -s /Volumes/DanBackup/Websites/wpdtrt-plugin-boilerplate

Edit the boilerplate on local dev, commit as appropriate
Test the boilerplate by running the NPM scripts from the boilerplate's package.json
Test plugin code compatibility by running the NPM scripts from the plugin's package.json
When all tests pass, push to Github
When all Travis tests pass, bump the version on local dev, then push to Github again

Note: The above process is recommended as an alternative to updating composer.json to target dev-master. Generated plugins target specific versions of the boilerplate for clarity, and may require other generated plugins for unit testing. Therefore it would be difficult to change all dependencies to use the dev-master version, and attempting to composer update to this version would likely fail.

Test changes

Lint code and run unit tests:

$ yarn run test

If this fails, the test environment may be missing or out of date. Reinstall it first:

$ yarn run install_deps
$ yarn run test

Release an update

Boilerplate

Test changes, on local dev
Commit tested changes

Update canonical boilerplate version in package.json

# Disable automatic tag creation when yarn version is run
npm config set version-git-tag false

# Change node version
n 11.15.0

# Do versioning
npm run version

This automatically runs the script of the same name, to trigger DTRT WordPress Plugin Bump
```
# Change node version
n 11.15.0

# runs automatically
npm run version
```

Update readme.txt:

* Fixed issue foo with bar (#123)
* Added unicorns (#456)

Commit with similar message
Push.
If tests pass, and log is clear, tag and push again.
Update Github Release notes

Generated plugin

Test changes, on local dev
Commit tested changes
Update the boilerplate version in composer.json
Download the latest packages and update the autoload file:
```
composer update
```

Update canonical plugin version in package.json

// Disable automatic tag creation when yarn version is run
yarn config set version-git-tag false

// Do versioning

This automatically runs the script of the same name, to trigger DTRT WordPress Plugin Bump
```
// runs automatically
yarn run version
```