marvinlabs/wpca-products-build-environment

Required software
First time setup
Vagrant as local MAMP/WAMP/XAMP/EasyPHP/... replacement
- Let's develop something
- Let's call it a day
Grunt tasks

Required software

Install Ruby
Install Git
Install NodeJS
Install Virtual Box
Install Vagrant
Install xGetText
Install Transifex

First time setup

Checkout this build-environment repository to a folder (e.g. c:/wpca/)
Run vagrant plugin install vagrant-hostsupdater to install a plugin that will automatically update your hosts file
Run npm install -g grunt-cli to install Grunt
Run npm install -g windows-build-tools to install some Visual Studio Build tools (and also Python if you don't have it already on your computer)
Run npm install in the build environment directory
Run grunt gitclone to get all the necessary plugins, add-ons and tools
Run grunt gitcheckout to switch all working branches to develop
Run . up-vagrant.sh to install the VM

Open vagrant/www/wordpress-local/public_html/wp-config.php and add the following constants

/**
 * Custom config for WPCA
 * @see https://github.com/marvinlabs/wpca-products-build-environment/issues/5
 */
// Environment related
define('WP_ENV', 'development');
define('WP_CONTENT_DIR', __DIR__ . '/wp-content');
define('WP_CONTENT_URL', 'http://' . $_SERVER['HTTP_HOST'] . '/wp-content/');
define('WP_PLUGIN_DIR', dirname(dirname(dirname(__DIR__))) . '/wpca-plugins');
define('WP_PLUGIN_URL', 'http://' . $_SERVER['HTTP_HOST'] . '/wp-content/plugins/');

// Errors display
define( 'WP_DEBUG', true );
define('SAVEQUERIES', true);
ini_set('display_errors', 1);
define('WP_DEBUG_DISPLAY', true);
define('SCRIPT_DEBUG', true);

Open vagrant/config/nginx-config/nginx-wp-common.conf and comment out the following lines or you will get an error like Multisite support not enabled when browsing the My files page.

# Pass uploaded files to wp-includes/ms-files.php.
# rewrite /files/$ /index.php last;

# if ($uri !~ wp-content/plugins) {
#    rewrite /files/(.+)$ /wp-includes/ms-files.php?file=$1 last;
# }

Vagrant as local MAMP/WAMP/XAMP/EasyPHP/... replacement

This build environment makes use of Vagrant (and more specifically of VVV) to provide a web server contained in a virtual machine.

Please refer to the documentation of VVV to know how to install and start this virtual machine. Basically, all files for your webserver will be shared in the folder vagrant/www.

Hint: if you still want to use AMP or any other local server, you can edit the grunt/config/sync.json file and add your web server's plugins folder to that list*

Hint: to debug you can use xdebug. Here is some tutorial to setup PhpStorm to work with that VM

Let's develop something

When you want to start developing, run . vagrant-start.sh which will:

start the vagrant VM (the first time you do it can take a few minutes)
Open the vvv.test URL in your favorite browser so you can access the sites easily
TODO : watch for changes in the wp-plugins for LESS, JS, PHP.

Let's call it a day

Once you are finished, just run . vagrant-stop.sh to halt gracefully the VM.

Let's re-provision the VM

Sometimes, you may pull the last environment-build from this repo, and see that some changes have been made in the vagrant-config folder. In this case, you can re-provision the VM by running . vagrant-provision.sh.

Note : This command run a vagrant up --provision and also copy some config files before that. If the VM is already running, do not forget to stop it before by running . vagrant-stop.sh.

You will notice a folder called vagrant-config. All the directories and files within this folder will be recursively copied to vagrant/ before provisioning. This folder contains some VVV customisations for our build-environment, so the files should not be edited there.

Grunt tasks

All grunt tasks shall be run in the build environment directory directly

Combined (aka. most useful) tasks available for all plugins

`grunt prepare-languages`

When translations need a refresh.

Runs sequentially: checktextdomain, then makepot, then potomo

`grunt prepare-vendors`

When you are updating the vendors (via bower or composer). Some of them are copied and prepared for use in WP Customer Area projects (for instance, Bootstrap classes are prefixed - prefixed bootstrap is no more used).

Runs sequentially: copy:copy-bootstrap, then copy:prefix-bootstrap

`grunt prepare-assets`

When asset sources have changed and we need to compile them

Runs sequentially: copy:libs-assets-extras, then prepare-dev-assets, then less, then postcss, then uglify, then update-cuar-versions

`grunt prepare-archives`

When you are ready to release a new version and want to build a zip file for publishing your add-on

Runs sequentially: compress

`grunt prepare-dev-assets`

When you need to update the nuancier CSS file for development purpose. It means that when developping on local.wordpress.test, you'll get a "open" button on the bottom left corner of the screen that will open a nuancier including almost all bootstrap variables and their values.

Basically, the dev-vars task creates a CSS file from Bootstrap variables parsed values, and the second one compile it so we can import it. The CSS import of this file is done into customer-area/skins/frontend/master/cuar-functions.php

Runs sequentially, for each skin: dev-vars:{skin-slug}, then less:cuar-skin-{skin-slug}-less-vars

`grunt dev-skin:frontend-{skin-slug}`

Everytime a skin is registered in grunt/config/skins.json, and that you want to work on it, you can compile it's style by running this command. It will also allow you to use sourcemaps, and it will parse the bootstrap variables and their values so you will get a nuancier showing you all the colors from your skins while developping. This will also compile the JS files and allow sourcemaps when the {skin-slug} is master.

`grunt gitclone:{plugin-slug}`

When you need to clone some of our required repositories. This will clone the master branch.

Note that this task can be run as a standalone task without a {plugin-slug} so you can pull all repositories at once.

`grunt gitcheckout:{plugin-slug}`

When you need to checkout the develop branch for one or more add-ons.

Note that this task can be run as a standalone task without a {plugin-slug} so you can pull all repositories at once.

`grunt gitfetch:{plugin-slug}`

When you need to fetch updates from a plugin repository.

Note that this task can be run as a standalone task without a {plugin-slug} so you can pull all repositories at once.

`grunt gitpull:{plugin-slug}`

When you need to pull updates from a plugin repository.

Note that this task can be run as a standalone task without a {plugin-slug} so you can pull all repositories at once.

`grunt gitreset:{plugin-slug}`

When you need to hard reset a plugin repository to its HEAD commit.

Note that this task can be run as a standalone task without a {plugin-slug} so you can pull all repositories at once.

`grunt start-dev`

When you want to start working with your local web server

Runs sequentially: watch

Tasks available for all plugins

`grunt checktextdomain`

Checks that all the source code uses the proper text domain in internationalization functions

`grunt makepot`

Create the POT files from the source code

`grunt potomo`

Compile all .po files to .mo files

`grunt sync-cuar-commons`

Use this when you want to copy all files required by an add-on from the main plugin.

Copies customer-area/libs/cuar/** to each addon's folder

`grunt less`

Compile the LESS source code into CSS stylesheets.

LESS files are taken from:

Base plugin skins' src/less folder and compiled to the skin's assets/css folder
3rd party add-ons' src/less and compiled to the add-on's assets/css folder

`grunt autoprefixer`

Remove/add prefixes for CSS properties. This is usually run as post-processing of the less task. This task is run on the CSS assets of the base plugin skins as well as 3rd party add-ons' CSS assets.

`grunt uglify`

Combines and compresses Javascript files into a unique file.

JS files are taken from each plugin's src/js folder and compiled to the plugin's assets/admin/js and/or assets/frontend/js folder

`grunt bump-version`

Update the version number for a given plugin. Usage: grunt bump-version:plugin:mode

Examples:

grunt bump-version:customer-area:minor
grunt bump-version:customer-area-login-form:major
grunt bump-version:customer-area-notifications:patch

`grunt wp_readme_to_markdown`

Convert each readme.txt file to a README.md file more appropriate for git repositories

`grunt compress`

Make a zip file of each plugin and place it in the releases folder. File inclusion/exclusion can be adjusted in the file named grunt/config/build.json.

`grunt watch`

Watch for file changes in:

the wp-plugins folder to start a synchronisation task with the local web server TODO : watch for JS, CSS LESS files

Tasks specific to the main WP Customer Area plugin

`grunt update-libs`

Use this when you need to update all the libs for WPCA. This will run updates from bower, composer, and custom libs, copy the required vendors files to WPCA, and recompile LESS and JS assets.

`grunt tx-push`

Use this when you have finished developing something and need to update the translation repository for translators.

Note: You need to create the .transifex file with your credentials to wp-translations.org before you can use this task

Run the prepare-languages:customer-area task
Push POT file to wp-translations.org

`grunt tx-pull`

Use this when translators have finished working and you need to update the PO/MO files in the plugin folder.

Note: You need to create the .transifex file with your credentials to wp-translations.org before you can use this task

Push latest PO files from wp-translations.org
Compile PO files to MO files

Debugging JS

For instance, for Switch Users, in Chrome.

In the panel "sources", we see a yellow folder in the section NETWORK (not Workspace).
The JS file appears. When clicking on it, we see the right source file, which means that sourcemaps are correct.
We then need to add that file to the workspace: right clic > add folder to workspace > pick the folder wp-plugins/customer-area-switch-users/src/js/frontend
Authorize access to Chrome and reload the page
Then clic on the workspace file and pick map to network resource
You can then select switch-users.js in the scripts loaded from network