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
  • Combined (aka. most useful) tasks available for all plugins
    • grunt prepare-languages
    • grunt prepare-assets
    • grunt prepare-archives
    • grunt prepare-dev-assets
    • grunt dev-skin:frontend-{skin-slug}
    • grunt gitclone:{plugin-slug}
    • grunt gitcheckout:{plugin-slug}
    • grunt gitfetch:{plugin-slug}
    • grunt gitpull:{plugin-slug}
    • grunt gitreset:{plugin-slug}
    • grunt start-dev
  • Tasks available for all plugins
    • grunt checktextdomain
    • grunt makepot
    • grunt potomo
    • grunt sync-cuar-commons
    • grunt less
    • grunt autoprefixer
    • grunt uglify
    • grunt bump-version
    • grunt wp_readme_to_markdown
    • grunt compress
    • grunt watch
  • Tasks specific to the main WP Customer Area plugin
    • grunt update-libs
    • grunt tx-push
    • grunt tx-pull

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

• 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;
  # }
  

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

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.

Once you are finished, just run . vagrant-stop.sh to halt gracefully 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.

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

When translations need a refresh.

Runs sequentially: checktextdomain, then makepot, then potomo

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

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

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

Runs sequentially: compress

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

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.

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.

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.

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.

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.

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.

When you want to start working with your local web server

Runs sequentially: watch

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

Create the POT files from the source code

Compile all .po files to .mo files

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

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

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.

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

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

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

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.

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

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.

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

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

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