LFEvents Developer Instructions
LFEvents uses a Continuous Integration (CI) infrastructure via github, CircleCI and Pantheon. These instructions help you get a local instance up and running and explain how to run the various tests.
All these tests are run by CircleCI on each commit to the master branch, whenever a PR is created on a branch, and on each commit to a branch that has a PR open. Such branches will have a multidev env automatically created for them by CircleCI to facilitate showing to stakeholders. Once the PR is merged, the env will be automatically deleted.
Install Local Instance
Install Lando (a Docker Compose utility / abstraction layer). On a Mac using brew, the command is
brew cask install lando.
You need a GitHub personal access token to use in place of a password for performing Git operations over HTTPS.
(these steps were derived from instructions provided by Pantheon)
- Clone this repository with HTTPS (not SSH):
git clone https://github.com/LF-Engineering/lfevents.git
- Note that the repo does not contain all of WordPress, 3rd-party themes and plugins. They will be pulled in via composer in step 4.
lando initand use the following values when prompted:
From where should we get your app's codebase?>
current working directory
What recipe do you want to use?>
Enter a Pantheon machine token>
[enter the Pantheon token you got above]
lando startand note the local site URL provided at the end of the process
lando composer install --no-ansi --no-interaction --optimize-autoloader --no-progressto download dependencies
lando pull --code=noneand follow the prompts to download the media files and database from Pantheon:
Pull database from?>
Pull files from?>
You will need to compile the theme css/js before the site will render correctly:
- Go to the theme directory:
- Install the Node.js dependencies:
- Compile the files:
npm run build
- Go to the theme directory:
Visit the local site URL saved from above. To find it again run
In the admin you will need to edit the Search & Filter settings. The full url to the result pages are hardcoded in the "Display Results" of each filter. These will need to be set to the correpsonding local instance url.
Get your browser to trust the Lando SSL certificate by following these instructions. This step isn't essential but will stop you having to keep bypassing the privacy warning in your browser. On MacOS Catalina, I also had to manually go into Keychain Access and set the *.lndo.site certificate to “Always Trust”. See screenshot.
You can stop Lando with
lando stopand start it again with
Composer, Terminus and wp-cli commands should be run in Lando rather than on the host machine. This is done by prefixing the desired command with
lando. For example, after a change to composer.json, run
lando composer updaterather than
lando pull --code=noneat any time to pull down a fresh copy of the database and files from Pantheon
LFEvents uses a fork of the FoundationPress theme. To optionally use Browsersync, copy
config.yml (git ignores this file) and change the Browsersync URL (line 4) to
npm start to compile CSS and JS to
dist/ (git ignores this directory) as changes are made to the source files. When deployed,
dist/ files are compiled and minified with
npm run build through CircleCI.
Create a behat-local.yml like this:
cp tests/behat/behat-pantheon.yml behat-local.yml
Edit behat-local.yml to have the bottom half of the file like this. You'll need to fill in your own admin password and update the
extensions: Behat\MinkExtension: base_url: https://lfeventsci.lndo.site browser_name: chrome sessions: default: chrome: api_url: "http://localhost:9222" validate_certificate: false PaulGibbs\WordpressBehatExtension: users: - roles: - administrator username: admin password: xxx default_driver: wpcli site_url: https://lfeventsci.lndo.site/wp path: web/wp DMore\ChromeExtension\Behat\ServiceContainer\ChromeExtension: ~
You need to have chrome running in headless mode in order for the tests to run. I accomplished that on macos like this:
alias chrome="/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome" chrome --headless --remote-debugging-port=9222 https://www.chromestatus.com&
Then to run the tests:
Wraith performs visual regression tests by comparing two versions of the site. It is a great way to spot unintended render issues across the site.
Install wraith system-wide using the instructions here.
Then setup your own config file:
cd wraith cp configs/capture-local.yaml.template configs/capture.yaml
Edit configs/capture.yaml to update the new domain to point to your local instance.
wraith capture configs/capture.yaml
View the diff gallery:
The CircleCI process has a job to sniff the code to make sure it complies with WordPress coding standards. All Linux Foundation code should comply with these guidelines.
phpcs and the WordPress Coding Standards for PHP_CodeSniffer come as part of the repo and are installed in the vendor directory by composer. phpcs can be run on the command line like this:
./vendor/bin/phpcs --standard=WordPress ./web/wp-content
For convenience on local instances, use this command to ignore particular files and ignore warnings:
./vendor/bin/phpcs -n -s --ignore=*/dist/*,*/node_modules/*,*gulpfile*,*/uploads/*,*/plugins/*,*instantpage*,*pantheon* -d memory_limit=1024M --standard=WordPress ./web/wp-content
It's even more convenient to install into your text editor.
Since the lfeventsci repo includes phpcs via composer, it will use that version of the binary even though you may have phpcs installed system-wide. So in the root of the repo you'll need to run the following so that it can find the WordPress standards from within your code editor:
./vendor/bin/phpcs --config-set installed_paths ~/Sites/lfeventsci/vendor/wp-coding-standards/wpcs
Upgrading WordPress core, themes and plugins
composer.lock is generated from composer.json only when explicitly calling the
composer update function. Any additional themes or plugins can be added first to composer.json and then
composer update package is run to update composer.lock and pull in the new files. Dependencies are pegged to a version according to the composer versioning rules.
It's good practice to keep WordPress and all plugins set at their latest releases to inherit any security patches and upgraded functionality. Upgrading to a new version, however, sometimes has unintended consequences so it's critical to run all tests before deploying live.
To upgrade the version of a dependency, follow these steps:
Edit composer.json to set the new version rule
lando composer update [package]to update composer.lock for just that package or run
lando composer updateto upgrade all packages to the latest versions which satisfy the constraints set in composer.json
Test the site locally
Check in to github and allow the tests to run
Test the dev instance to make sure all looks good