How we do WordPress at Common Knowledge

Why WordPress?

We aren’t a WordPress agency. We aren’t a agency (for a start) and WordPress is among the suite of tools we might bring to a situation.

• It’s boring technology
• People ask for it and are familiar with it.
• Lots of people can maintain it who aren’t us.
• The community are user centric, not developer centric.
• We actually want to contribute to the commons and so do Automattic.
• We think the direction of travel with full site editing is very exciting to do what we do: help organisers build power and get the tech stuff out of the way.

What sites have we done in WordPress?

Our flagship WordPress site is the Platform website. It has a great combination of excellent aesthetics and really well done code.

The flagship "build a WordPress site extremely rapidly at scale for a campaign" is Enough is Enough. The site had several million hits and hundreds of thousands of sign-ups.

Our approach to WordPress

Our approach to WordPress is to:

1. Keep it simple

We like to use WordPress directly where we can, rather than rely on plugins or things that bend WordPress into usual shapes. Sometimes another technology is more simple to do what we need. WordPress is a great content management system. It can be made to do a lot beyond that, but should it? We step back and ask ourselves this question. This simplicity extends to how WordPress is deployed. Ideally a WordPress site should ship with under 10 plugins installed.

2. Keep up to date with the latest WordPress ways of doing things and lean into them

In contrast to some of the conversation in the WordPress community, we think the Gutenberg changes to WordPress are broadly a good thing, because they focus on allowing the user of the site to do more without code level interventions by developers. For organisers, used to asking someone to make changes all the time we think this is game changing. So we try to stay up to date with the bleeding edge of WordPress development, because it aligns with this way forward. Break this rule, only when it conflicts with 3.

3. Serve the users of the site first, last and always

This goes without saying, but our goal is to serve users in making WordPress sites that are politically effective and in the hands of organisers to do their work. Therefore we lean into this, rather than necessarily making WordPress sites that are perfect environments for developers to work on.

Setting up WordPress

We manage WordPress as much as possible as a 12 factor app. For facilitate this, we set up WordPress using the Bedrock boiler plate.

https://github.com/roots/bedrock

Over the top of this, we add a very simple Docker setup for running WordPress sites without needing to install PHP on your machine.

The following starter repository shows how it is done. New WordPress projects should begin from this template.

https://github.com/commonknowledge/wordpress-starter-template

We should be keeping this up to date. If it is not up to date for whatever reason, the first step should be to update this repository, then draw from it to make any future changes.

Though there is a bit of a maintainability trade off for future non-Common Knowledge developers in using Bedrock (not every WordPress developer will have seen it), we think having WordPress maintained in this clear manner outweighs those risks. This is partly because Bedrock is well documented and widely used throughout the WordPress community.

Coding standards

This reflects the state of play and we need to develop our ideas further, as we are between two styles.

• Within Common Knowledge projects there are some projects that use PSR-2 style PHP. This is the style that Roots commonly use in their WordPress work.
• Sometimes we also use Automattic’s WordPress style, but don’t enforce it with PHP_Codesniffer.
• Probably we should go with the latter, as this can mean that work we do could be passed into WordPress.com as a blessed plugin, meaning it can be installed there.
• The only reason not to do this is Automattic’s JavaScript style is a bit esoteric compared to most ways people code JavaScript.

Maintaining content

• In order to get the website into a usable state, you also typically need the content.
• To make this easier, we maintain some content as a simple WordPress export in a seeds/ directory in the repository. This can be imported with WP-CLI.
• We need to fresh this occasionally from backups from production sites.

Themes

• WordPress themes we make are WordPress full site editing themes from the ground up.
• This means extensive use of theme.json - developers should be roughly familiar with the extent to which this can be used by examining the WordPress documentation.
• We don’t think that the Gutenberg story around responsive styles is amazingly satisfactory, so will from time to time use CSS to make overrides.
• If we encounter a non-full site WordPress theme, we convert it into a full site theme that is Gutenberg native with the minimum of fuss.
• Starting a theme entirely within the WordPress editor using [create-block-theme](https://github.com/WordPress/create-block-theme) is a fine way to proceed and we encourage these kind of low code interventions as a starting point.
• When it comes to creating custom blocks:
  • We use CarbonFields as a first port of call to get something going - this allows quick creation of custom blocks without delving down into lower levels of WordPress
  • Further than that, we can make them from scratch as needed
• For creating CSS styles, we prefer Tailwind. However, we prefer using WordPress theme.json styling to keep native to WordPress.
• For front end elements, build chains should be a simple yarn build
• Custom post types that are needed for themes should exist at the theme level. This isn’t a satisfactory solution, but will do for now.
• We currently don’t use Sage from Roots to do themes. Though there might be a fairly good argument to do so, it feels like bending WordPress this far from it’s normal paradigms to resemble Laravel more closely makes maintenance harder for non-Common Knowledge developers who aren’t used to, say, using Blade in WordPress templating.

Plugins

• We try and keep the amount of plugins to a minimum, recognising this is a common source of maintenance problems for WordPress and site slowness in general.
• Plugins with no support should not be used.
• We manage WordPress plugins using WordPress Packagist and standard conventions of using Composer in PHP writ large.
• For paid plugins, we sometimes don't have any good ways of managing them. If the plugin itself supports Composer, that should be used. Otherwise, we tend to keep them as private repositories on GitHub. We could attempt approaches like this in future. This product looks interesting. Or we can lobby Outlandish to do this, in WordPress Packagist itself.
• Plugins we like, that should be installed by default on WordPress load out are:
  • Wordfence - this should be installed by default on all WordPress installations we build. We should turn on 2 Factor Authentication by default.
  • Yoast SEO - very detailed and powerful SEO management. Also allows the setting of custom share cards.
  • GiveWP - WordPress giving plugin that uses Stripe.
  • Gravity Forms - a paid plugin for creating forms that is very powerful and adaptable.
  • WooCommerce - Automattic’s blessed WordPress plugin for shops and subscriptions. This follows our WordPress approach by not staying sympathetic to the basic ways WordPress approaches things, so we like it.
• If we are writing full custom functionality, it should be produced as a plugin.

Deploying WordPress

• The aspiration is that WordPress sites should be:
  • Configured in code. We can use Dictator to facilitate this - keeping the state of the WordPress backend on disk and auditable as text. We are keeping an eye on Intervention as an even better way of doing this. If a plugin is in the composer.json file we assume that it is intended to be activated on deployment. We use automated scripts to activate plugins in this way.
  • We use [jq](https://stedolan.github.io/jq/) to parse the contents of the composer.json file and pass a list of the plugins to a script that activates them using the WP-CLI. This relies on the following assumptions
    1. jq is installed on the remote server - this has proved to be the case on WP Engine.
    2. Non third party plugins (i.e. those created by the organisation and hosted on GitHub) follow a naming convention as a the jq script relies on text matching.
  • Reproducible on local machines with ease from a simple set of instructions in a [README.md](http://README.md) or
  • Have continuous deployment setup that deploys code as fast as possible to environments.
• If we have a choice of host, we will go for Kinsta. At the moment they are the best in class WordPress hosting.
• We also have scripts that automate deployment to WP Engine, another common WordPress host.

Having continuous deployment set up for WordPress is sometimes a bit tricky, but the reason we do this is to enable organisers to have what they need to do their work as fast as possible.

Noted issues

Here we note common bugs that come up during our WordPress work

• The WP_HOME variable in our .env file should never have a trailing slash e.g. WP_HOME='https://mywordpresssite.kinsta.cloud'