This document provides an overview of Kanopi tooling. Generally, these tools are encouraged or required to be used in favor of others. Ideally, Kanopi would like to use the same (or very similar) tools across all projects. This helps minimize switching costs for developers when moving through tasks or even whole projects.

Rules governing client site tools are less flexible. Internal, experimental projects are more flexible.

Inherited support client sites are more flexible. How much work is put into “standardizing” an inherited support site will depend on budget and project deadline needs.

Several of these tools work in conjunction. For example, a WP Engine-hosted site might run Tugboat previews, which may then run BackstopJS visual regression testing.

As a part of Kanopi’s default laptop configuration via our mobile device management (MDM) system, users are not system administrators on their devices by default. Configuring and managing machines relies on the following applications.

Privileges App - allows users to request sudo power. Disabling administrator rights by default prevents unintended machine changes. It also helps to prevent malicious actors from doing bad things. To activate administrative privileges, click the lock icon in your Dock. Once activated, you will receive admin (and therefore sudo ) rights for up to two hours. This is typically a required step when running commands in the terminal and elsewhere.

Kanopi’s preferred code editor is Visual Studio Code. Some developers use PHPStorm; however, it is preferable to use VS Code as that is the officially supported code editor in Kanopi.

VS Code can be configured using any plugins desired, of course. Some extensions are strongly recommended:

⁠

PHPCS⁠

(note: while this exact extension is not required, projects should generally meet

phpcs standards⁠

for their CMS of choice. In other words, there must be some way for code to achieve phpcs standards.) In general, projects should adhere to the standard

WP phpcs standards⁠

. Various support projects may have custom standards applied — check the README for any differences in a given project.

⁠

WordPress Snippets (for WordPress developers)⁠

⁠

Git Graph⁠

⁠

PHP Debug⁠

⁠

Git⁠

- Kanopi’s preferred version control. Kanopi encourages developers to use the command line for interacting with Git. GUIs are permitted but may not be supported internally.

⁠

GitHub⁠

- Kanopi’s preferred version control management system. All developers must have a GitHub account. Kanopi uses various teams within the GitHub organization. Developer GitHub accounts will be added to teams and repositories as needed. You may use your existing GitHub account or optionally set one up that is Kanopi-specific.

⁠

Left Hook⁠

- A tool that runs commit hooks on code. For example, commit hooks can be configured to run PHPCS. If PHPCS fails, the commit cannot be pushed to the remote repo. It can be installed via npm or brew if necessary for a given project.

See

Version Control⁠

for more information.

For new builds, Kanopi has several starter kits and base builds available. These starter kits help scaffold a new site quickly and in a standardized Kanopi way. Support projects can emulate the starter kits for a most ideal scaffolding setup - although again, budget and client needs dictate the setup for these projects.

The goal is to avoid building the same content types and components and build processes on almost every site. Reusable code allows the sales department the freedom to bid more competitively.

⁠

Kanopi WP Basebuild⁠

- Developers can use WP Basebuild to quickly create WordPress sites with recommended tooling and many best practices already in place. WP Basebuild contains a full and robust suite of the tools used for sites, such as Docksal, Bootstrap, and Kanopi Pack.

On the Drupal side, the

base starter⁠

includes the configuration, templates, and styling needed to jump-start a Drupal 9 build.

Drupal starters:

⁠

https://github.com/kanopi/drupal-starter⁠

⁠

https://github.com/kanopi/drupal-acquia⁠

⁠

More Drupal tools:

Kanopi Design Component Library is an initiative to bridge Kanopi’s Figma and Storybook component library. There are two iterations.

KDCL Basic

KDCL - which will be connected to Figma through Style Dictionary and Figma Tokens

⁠

Kanponents⁠

, which houses common UCSF paragraphs

⁠

Wanzer⁠

, a module that installs UCSF content types and related building blocks

⁠

Toland⁠

, a base theme with common UCSF styles.

⁠

Composer⁠

- Composer manages PHP dependencies. Both Drupal and WordPress projects can be easily managed using Composer. The exact version of composer used changes from project to project, and some projects will have specific version requirements.

WP Basebuild comes with composer preinstalled.

⁠

WordPress Packagist⁠

provides a Composer repository that mirrors all public WordPress plugins and themes.

⁠

Drupal Packages⁠

provides various composer packages that can be installed to a Drupal project.

⁠

Kanopi Packagist⁠

- Houses custom Kanopi projects using a composer-based repository.

⁠

Composer Basics Handout by Mike Anello from Drupal Easy⁠

⁠

Kanopi’s preferred local development environment is

Docksal⁠

. Docksal builds and interacts with virtual environments that match production as closely as possible. Sean works on Docksal directly as a contributor, so an excellent Docksal resource already lives in-house.

Docksal uses Docker and Docker Compose to create fully containerized environments for projects. All the configurations and requirements are packaged into one container. These sites can then be spun up without additional local machine installations. Project-specific tools/dependencies are installed and run in the Docksal container and are independent of the local machine.

For example, suppose a terminus or composer command must be run from a local site. Normally terminus or composer would need to be installed on the local machine. The commands are unavailable until installed on the local machine. With Docksal, those dependencies are available in the Docksal container. The commands can be run and used from the Docksal container, regardless if they are installed on the local machine or not.

For help and assistance with Docksal, please see the

#dev-pipeline Slack channel⁠

Docksal is not specialized in either WordPress or Drupal

Docksal is lightweight and not resource intensive

All projects/containers are independent of each other

Each project/container can have its own stack requirements and different versions of the same service

Each container/project can be managed independently and extended with any service

Tools such as Composer, Drush, Drupal Console, Terminus, npm, and WP-CLI are built-in. These tools don’t need to be separately installed and managed on the local machine.

The WP Basebuild uses Webpack as

Kanopi Pack⁠

. This is Kanopi’s preferred method of task running.

Resources:

Kanopi Pack Theme Integration⁠

⁠

Through inherited support sites, other task runners such as Grunt, Gulp, and standard Webpack are frequently supported.

⁠

https://stylelint.io/⁠

- a CSS linting tool that ensures code quality and standardization.

⁠

https://eslint.org/⁠

- A JavaScript linting tool that ensures code quality and standardization.

⁠

SonarQube⁠

- A PHP code quality and code security tool.

https://github.com/kanopi/sonarqube-report⁠

can be used to run a SonarQube report within projects.

⁠

WP-CLI⁠

- A command line interface for WordPress. This is an extremely powerful tool that allows imports, exports, running custom scripts, and more — all via the command line.

⁠

Drush⁠

- Drush is a command line shell and Unix scripting interface for Drupal. Drush core ships with lots of useful commands and generators. Similarly, it runs update.php, executes SQL queries, runs content migrations, and misc utilities like cron or cache rebuild.

Some of the things that can be done with CI/CD include:

BackstopJS visual regression testing

Lighthouse and pa11y accessibility testing

PHP code quality tools such as PHPCS, PHPD, PHPStan, and SonarQube

Asset compilation with grunt, gulp, webpack, etc.

⁠

https://github.com/kanopi/circleci-orbs⁠

⁠

CircleCI is a continuous integration (CI) tool. CircleCI facilitates code deployments to various environments and automated tooling workflows. Orbs are a set of automated and reusable tasks that can be implemented to help speed up different tasks within a Circle buil

See [CircleCI]({{ site.baseurl }}/circleci) for more information.

⁠

https://github.com/kanopi/cms-updates⁠

⁠

Automated CMS updates automatically run CMS updates on Drupal and WordPress sites. The automated script runs to update core and contributed files and libraries and creates a testing environment (whether that’s a multidev, Tugboat preview, or another environment depends on the project). Finally, the automated CMS tool alerts the development team that the environment is ready for review, typically through a pull request.

Dependabot provides automated dependency updates built into GitHub. Dependabot will scan a repository looking for outdated dependencies. It will then create a pull request in the repository, requesting updates. Dependabot PRs are mostly useful when dealing with custom build tools and custom-written code.

There is not much point in Dependabot PRs for updating the tooling within a third-party plugin, for example, as that third-party code is entirely within the control of the said third party. In other words, when Dependabot opens a PR to update Gulp in Alice’s Amazing WordPress Plugin, that PR can be closed without comment. It’s up to Alice to update the plugin.

A note about accessibility testing — automated testers do not capture all potential issues. Some level of manual testing is required.

Automated Testing

The following automated tools are used to test accessibility. As part of continuous integration, CircleCI can run some automated testing via orbs.

⁠

https://intranet.kanopi.com/departments/technology/resources/a11y_teaching__learning_audit_process__tools⁠

⁠

Command Line Tools

⁠

pa11y⁠

(often, but not always, configured through CircleCI)

Browser-Based Tools

⁠

WAVE⁠

⁠

Deque Axe Devtools⁠

⁠

SiteImprove⁠

⁠

Manual Testing

Manual testing includes:

Reading the page with a screen reader. Testing with a screen reader does require some special learning and direction. The following tools are free.

⁠

NVDA⁠

⁠

Chrome voiceover⁠

⁠

MacOS voiceover⁠

⁠

Testing heading levels and ensuring headings occur in descending order (h1, h2, h3, h4, h5, h6).

⁠

Headings Map for Chrome⁠

Headings Map for Firefox⁠

- A browser extension that displays the heading structure of a webpage.

Internal Resources

Internal resources for accessibility testing:

⁠

#accessibility⁠

Kanopi channel

Tugboat is a special preview building service used on sites that do not have Pantheon multidevs. Pantheon multidev environments mirror the purpose of Tugboat.

Tugboat builds a testing environment that is completely separate from the production environment. This is helpful for various workflows and client testing. For projects configured with Tugboat, Tugboat Previews are automatically built when a pull request is opened. Additional tools, like Lighthouse and Visual Diffs regressions, can be configured to run against Tugboat Previews.

⁠

http://intranet.kanopi.com/download/.attachments/tugboatpaulzenbusiness20210512mp4⁠

⁠

Note, Tugboat will not persist database changes across builds. If the content is modified in a Tugboat environment — such as adding ACF fields, deleting or moving pages, or modifying a menu — these changes will not persist. Tugboat previews shut down after periods of inactivity. If they are reactivated, Tugboat spins up completely fresh, pulling a new copy of the database from production.

This limitation may complicate client testing. If many changes are required within a Tugboat preview, it may make sense to split the commits/deployments up.

For example, when adding a new post type Fax Machines to Bob’s Beeper Emporium site — it may make sense to:

Create a commit defining the post type and ACF fields.

Get that commit all the way up to production.

Enter some data into production.

Tugboat previews will then build with the expected data.

BackstopJS provides visual regression testing to ensure code changes don’t have unforeseen repercussions. Backstop essentially takes screenshots of a website before and after changes are applied. It then compares the two sets of screenshots, providing a “visual diff” for QA and testing. Backstop is useful for CSS changes, plugin updates, and third-party script updates.

Sometimes, visual regression testing is baked into local workflows or Tugboat.

⁠

BackstopJS⁠

⁠

Cacher Snippets

CircleCI:

https://snippets.cacher.io/snippet/1cd8e1241cde4a889e13⁠

⁠

htpasswd:

https://snippets.cacher.io/snippet/7fccb3d8ec3b4a5df739⁠

⁠

The goal of the Lighthouse initiative is for Kanopi’s portfolio and sites to rank in the top 25% and better of all sites on the internet against Google Lighthouse tests. Existing clients have chosen to work with Kanopi based on our Lighthouse scores.

Tests can be manually run using browser plugins or a CLI tool. Lighthouse tests can also be added to continuous integration tests on sites that have multidev environments.

Kanopi maintains a Lighthouse Dashboard for easy access to score information for these “index” sites.

The dashboard is located at

https://lighthouse-eos.netlify.app/⁠

(open / sesame)

The GitHub repository is located at

https://github.com/kanopi/lh_eos⁠

⁠

Kanopi works with various hosting environments. Every hosting environment and the tools provided in each environment are slightly different. The optimal setup also differs per project, based on the hosting environment used and that particular client’s needs.

⁠

Pantheon⁠

(WP & Drupal, WP multisites, & headless WP & Drupal)

⁠

Acquia⁠

(Drupal, Drupal multisites, and headless Drupal)

⁠

WP Engine⁠

(WP, WP Multisites, and headless WP)

⁠

PlatformSH⁠

(Everything and more)

⁠

Contegix⁠

(Everything and more)

⁠

Kinsta⁠

Flywheel⁠

, and

Linode⁠

(hosts that are used only if a client comes into support with a hosting contract already in place)

Features

Multidev environments provide standalone, separate environments for each code change. Often, Github pull requests are configured to create a multidev when opened.

Example: two separate PRs create two separate multidev environments, allowing the work to be reviewed in parallel.

Terminus is a command line interface that provides advanced interaction with Pantheon. Terminus provides access to almost everything in the Pantheon Dashboard in a terminal, as well as scripting and much more.

Example: take a backup of a Pantheon site through the command line, without going through the dashboard.

Quicksilver hooks into Pantheon workflows to automate Pantheon WebOps workflow. This allows the platform to run selected scripts automatically every hour, or when a team member triggers the corresponding workflow.

Example: clearing out real users from a WP database when the database is copied from live to dev.

Access

To see all projects in Pantheon, use the Kanopi organization dashboard. Developers/managers are not added to individual projects within Pantheon. When a developer is added to the Kanopi organization, they automatically get access to all Kanopi projects.

Features

Typically set up with three separate environments — development, staging, and production.

An “Advanced” tab in the dashboard allows the running of WP-CLI (but not SSH) commands.

With WP Engine, projects most frequently include Tugboat. This allows more flexible testing and deployment processes, as nothing is tied together when testing or deploying. Tugboat on WP Engine can essentially replicate the multidev feature on Pantheon, allowing multiple PRs to be reviewed in parallel without interfering with each other.

Cacher is Kanopi’s preferred method of sharing code snippets. It integrates with most IDEs, has a web app and browser extensions, and can sync to GitHub Gists. Cacher allows easy collaboration and discussion with other developers. When asking “how do I X…” — Cacher is a great place to start searching for Kanopi-specific workflows, snippets, and walkthroughs.

⁠

Zeplin⁠

- Kanopi’s preferred method of sharing final design assets. Zeplin gives developers a single, clean source of truth.

⁠

Figma⁠

- A collaborative interface and design tool. It’s free to install and is frequently used to deliver prototypes from the design team.

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.