Engineering Best Practices
Search…
Tools
Philosophy
The quality of a contributor's work can be reliably tied to the quality of their tools. Your editor (IDE), local development environment, code linters, unit testers, compilers, shell scripts, and other tools can all have a profound impact on your efficiency and quality. So it's important to always be thinking about how your tools and workflow can be improved.
- What are your pain points?
- What is tedious?
- What are things that you often miss or forget to do?
As much as possible, when you identify improvements, try and look for ways to automate their solutions with scripts. If a script isn't possible, write a checklist which you can follow to reduce your cognitive load and the dreaded context switching we all love so much.
The following are tools we use at XWP. This list will grow and change over time and is not meant to be comprehensive. Generally, we encourage, and in some cases require, these tools to be used in favor of other ones. Rules governing tools to be used and packaged with a client site will be much stricter than those used on internal projects.
Editors (IDEs)
Our recommended PHP editor (IDE) is PhpStorm, there is also another that is becoming more and more wide spread as of late, which is VS Code and is also a great alternative. They both have extensive support for JavaScript, CSS, HTML, Markdown, Twig, and Bash to name a few. We highly recommend adopting PhpStorm for consistency across our team and so that we can collaborate on optimal configuration and maximizing the features.
Code Checkers
The following should all be integrated into
wp-dev-lib and pre-configured there for use in your plugin or site project; they should integrated into your IDE, be run automatically before committing via the pre-commit hook, and also run after pushing to a pull request via Travis CI:Any additional references to code checker tools elsewhere in these best practices should be amended to this list.
Local Development Environments
When starting out, many developers edit PHP files on their local machine and then upload the changes via FTP to their production site to test. This is bad! A slightly better workflow is to have a separate staging server to upload changes to and test there. This is less bad, but still not good. Both of these are examples of cowboy coding.
Proper development workflow is always centered around version control. Code being deployed to a shared environment must always be first committed to version control or else risk being lost or overwritten. In order to test code without first having to commit it, it is essential for all developers to have a local development environment — a web server and database running locally.
There are a variety of solutions out there to get a local development environment up and running (e.g. MAMP and XAMPP), but we've found that Docker is a far superior solution. We typically use Docker paired with Lando or Vagrant and VirtualBox to build and interact with virtual environments that match production as closely as possible. There are many setups and configurations available, but here are a few that we suggest based on the project requirements:
- Docker + VagrantThe Docker with Vagrant and VirtualBox local development environment
wpsh-localcan be embedded within a plugin using Composer. Making it perfect for both open source or client plugins that have no other dependencies besides WordPress. You can see howwpsh-localis implemented in ourblock-extendscaffolding plugin. - Docker + Lando This WordPress development environment, built with Docker and Lando from the Google team that is focused on WordPress development, allows for core development, plugin development, and theme development. It is intended to largely be a Docker-based port of VVV.
- WordPress Core Recently WordPress Core built a local development environment directly into the repository that uses Docker and NPM. To have WordPress Core running at http://localhost:8889 you can do the following commands:1git clone https://github.com/WordPress/wordpress-develop.git2cd wordpress-develop/3npm install4npm run build:dev5npm run env:start6npm run env:installCopied!
- WordPress VIP Go Our VIP Go Site Boilerplate is a modern setup for WordPress VIP Go hosted projects:
- 🏭 Uses Composer for adding project dependencies, including plugins and themes.
- 🌎 Uses Composer autoloader for using any of the popular PHP packages anywhere in the codebase.
- 👩💻 Provides a local development environment based on Docker that can be run inside Vagrant without having to install Docker on the host machine.
- 🚀 Includes automated build and deploy pipelines to WordPress VIP Go.
- VVV Varying Vagrant Vagrants (VVV) use to be our standard Vagrant setup for client sites and local development. However, over the past few years has become used much less due to its slow provisioning.
Scaffolding
-
wp-dev-libThis is a development library that is great for adding coding standards, linting and automated testing even to legacy projects since checks are applied only to new code by default. - Gutenberg Plugin The
block-extendplugin has been developed as a starter for creating Gutenberg centric plugins and is also used during candidate coding challenges. - Customizer Plugin Our template plugin for scaffolding WordPress plugins called
wp-foo-barhas historically been used to scaffold Customizer centric plugins for both our clients and Core. However, it has not been kept up-to-date this past year with all the new shinny development and editorial tools coming into play. It either needs to be updated or deprecated. It's likely that theblock-extendplugin will somehow be merged back into this scaffolding.
Task Runners
Npm Scripts are bundled with Node and can be defined in
package.json of the project which make them really fast to configure and setup. These scripts can call Node package binaries for the project or serve as wrappers for Grunt, Gulp or Webpack tasks.Grunt is a task runner built on Node that lets you automate tasks like Sass preprocessing and JS minification. Grunt is our default task runner and has a great community of plugins and solutions we use for on company and client projects.
Webpack is a bundler for JS/CSS. It’s extremely useful when building larger JavaScript applications (i.e. React.js).
Package/Dependency Managers
Composer - We use Composer for managing PHP dependencies. Usually everything we need is bundled with WordPress, but sometimes we need external PHP libraries like “Patchwork”. Composer is a great way to manage those external libraries.
When a WordPress install is managed and maintained by an engineering team, and when the infrastructure supports it, plugins in a WordPress project can be easily managed using Composer. WordPress Packagist provides a Composer repository that mirrors all public WordPress plugins and themes.
NPM - We use
npm for managing JavaScript dependencies and is also great for generating scripts to accommodate our DevOps workflows. For example, we typically create scripts that lint, test, build, deploy, and pretty much handle everything we need to automate our processes.Version Control
Git - We use Git for version control. We encourage people to use the command line for interacting with Git. GUIs are permitted but will not be supported internally.
SVN - We use SVN, but only in the context of WordPress.com VIP. Again, we encourage people to use the command line as we do not support GUIs internally.
Command Line Tools
The mouse is the enemy. The book Pragmatic Programmer highlights the inefficiencies of interacting with a computer via a mouse. A workflow can be drastically sped up via keyboard commands. But think beyond “keyboard shortcuts” and the convoluted finger gymnastics they often involve (Ctrl-Alt-Command-Shift-A…). Think instead about the code you might write from your keyboard every day in PHP:
1
wp_insert_post( array( 'post_title' => 'Hello World' ) );
Copied!
These commands are articulated in computer language, here interpreted by PHP. However, this isn't really optimized for repetitive commands you write over and over and over again. A better language for repetitive tasks is Bash. When you open your computer's Terminal (e.g. iTerm2) you are being dropped onto a Bash prompt: an interpreter for code written in the Bash programming language.
1
git commit -m "First commit"
Copied!
When all of your instructions are composed of commands that are read by an interpreter like PHP or Bash, then you can turn your commands into scripts to automate your repetitive tasks, such as setting up a brand new WordPress install, or syncing a database down from production and translating its hostnames.
For WordPress, there is a de facto tool for interfacing with WordPress from the command line: WP-CLI. Becoming familiar with the commands available, and even writing your own commands, can greatly speed up your development workflow and allow you to script tasks for others to run without having to share a long complicated set of manual instructions. This is an extremely powerful tool that allows us to do imports, exports, run custom scripts, and more via the command line. Often this is the only way we can affect a large database (WordPress.com VIP or WPEngine). This tool should be installed by default in a development environment, if it's not create an issue on GitHub.
Accessibility Testing
We use a variety of tools to test our sites for accessibility issues. WebAim has some great resources on how to evaluate sites with a screen reader.
We’re also a fan of a few browser tools that lend us a hand when it comes to testing areas like color contrast, heading hierarchy, and ARIA application.
- Headings Map for Chrome or Headings Map for Firefox - A browser extension that allows you to see the heading structure of a webpage.
- The Visual ARIA Bookmarklet - A bookmarklet that can be run on a webpage and color codes ARIA roles.
- WAVE - A toolkit from WebAIM, that also has an extension for Chrome/Firefox. It evaluates a webpage and returns accessibility errors.
- Accessibility Developer Tools - A Chrome extension that adds an “Audit” tab in Chrome’s developer tools that can scan a webpage for accessibility issues.
- Tota11y - A visualization toolkit that can be used as a bookmarklet, and reveals accessibility errors on a webpage.
- Contrast Ratio - A color contrast tool to compare two colors against levels of conformance and see if they pass.
- Tanagaru Contrast Finder - Another color contrast tool that tests colors against the levels of conformance, but also provides you with alternatives should your provided colors fail.
Visual Regression Testing
We use visual regression testing to ensure code changes don’t have unforeseen repercussions. This provides a helpful visual aid to check against CSS changes, plugin updates, and third-party script updates.
- BackstopJS - A tool used to run visual regression tests that compares known reference states against updates.
VPN
Sometimes access to client and vendor resources is restricted to specific IP addresses so we use self-hosted Outline VPN servers on Google Cloud Platform to provide teams with fixed IP addresses in several geographical locations around the world—currently Montréal, Netherlands, Oregon, Singapore, and Sydney. Please reach out to Derek or Kaspars in the
#technology Slack channel to request access. Credentials will be sent securely through direct message on Keybase.After installing and configuring the Outline VPN client and connecting to one of the servers, use a service like ifconfig.io to confirm the IP address of the VPN endpoint. This IP address can be provided to the client or vendor for inclusion in the appropriate allow-list.
Note that all network traffic from your device to the public internet is routed through the VPN so please keep it connected only when necessary.
Secure Messaging
For exchanging sensitive information between teams, clients, and vendors we suggest using Keybase chat—which supports end-to-end encryption. Alternatively, if your Keybase account is associated with a PGP key, the message can be encrypted with your public key via this form and sent using any traditional channel such as email or Slack. Use
https://keybase.io/encrypt#kaspars where kaspars is your Keybase username to prefill the form with the correct recipient.Last modified 3mo ago