10up Scaffold

DEPRECATED. Use https://github.com/10up/wp-scaffold

At 10up, we strive to provide digital products that yield a top-notch user experience. In order to improve both our efficiency and consistency, we need to standardize what we use and how we use it. This theme scaffold allows us to share initial set up procedures to make sure all projects can get up and running as quickly as possible while closely adhering to 10up's high quality standards.

Dependencies

Node@^8.11.0 & NPM - Build packages and 3rd party dependencies are managed through NPM, so you will need that installed globally.
Webpack - Webpack is used to process the JavaScript, CSS, and other assets.
Composer - Composer is used to manage PHP.

Getting Started

Quick Start

Install 10up's command line tool for scaffolding new projects. You can download it from the Project Scaffold repository. Setting up a new theme is as easy as running create-10up theme theme-name-here in the terminal!

Browsersync requires a local development URL. This is currently set in the config/webpack.settings.js, as BrowserSyncConfig.proxy.

Direct Install

Clone the repository
Rename folder theme-scaffold -> your project's name
If copying files manually to an existing theme directory instead of cloning directly from the repository, make sure to include the following files which may be hidden:

.babelrc
.browserslistrc
.editorconfig
.eslintignore
.eslintrc
.gitignore

The NPM commands will fail without these files present.

Do case-sensitive search/replace for the following:
- TenUpScaffold
- TENUP_SCAFFOLD
- tenup-scaffold
- tenup_scaffold
- 10up Scaffold
cd into the theme folder
run npm run start

Webpack config

Webpack config files can be found in config folder:

webpack.config.dev.js
webpack.config.common.js
webpack.config.prod.js
webpack.settings.js

In most cases webpack.settings.js is the main file which would change from project to project. For example adding or removing entry points for JS and CSS.

NPM Commands

npm run start (install dependencies)
npm run watch (watch)
npm run build (build all files)
npm run build-release (build all files for release)
npm run dev (build all files for development)
npm run lint-release (install dependencies and run linting)
npm run lint-css (lint CSS)
npm run lint-js (lint JS)
npm run lint-php (lint PHP)
npm run lint (run all lints)
npm run format-js (format JS using eslint)
npm run format (alias for npm run format-js)
npm run test:a11y (run accessibility tests)

Composer Commands

composer install* (install packages)
composer update* (update packages)
composer lint (lint PHP files)
composer lint-fix (lint PHP files and automatically correct coding standard violations)

* If your host machine's local version of PHP is <7.2, composer may produce the following, or similar, error message:

 Problem 1
    - Installation request for 10up/wpacceptance dev-master -> satisfiable by 10up/wpacceptance[dev-master].
    - 10up/wpacceptance dev-master requires php >=7.2 -> your PHP version (7.1.23) does not satisfy that requirement

To suppress this error, add the flag --ignore-platform-reqs (ie. composer install --ignore-platform-reqs).

Automated Style Guide

The Theme Scaffolding ships with a default style guide you can find in /templates/page-styleguide.php. This file contains all the basic HTML elements you would find at the very top of the cascade (headings, typography, tables, forms, etc.) These base elements will be styled and displayed as you naturally build out your CSS. The style guide also automatically pulls in the color variables used in the project. Any hex codes added into /assets/css/frontend/global/variables.css will be automatically displayed in the style guide. To set up your style guide, you just need to create a new page in WordPress and assign it the "Style Guide" template.

If you need to update the core styles that power the style guide they are located in /assets/css/styleguide and will naturally process with the rest of the CSS.

As your site grows you can add components to the style guide by updating /templates/page-styleguide.php as you see fit. All the JS and CSS for the site will already be included in the template, so everything should just work.

Automated Accessibility Testing

Automated accessibility testing in the Theme Scaffolding is done with Pa11y and is executed with the command npm run test-a11y. You can find any configuration options inside your package.json file inside the testing object. You will see default URL options (homepage, article, search-results), but you can add as many as you'd like. The default script runs over the local URL and any others will run with an argument like npm run test-a11y production, over a production URL. You can also add more template URLs for testing like npm run a11y-test article-template. Be sure to check with your systems person on a project to make sure accessibility tests are also hooked up through the deploy process.

Compliance levels can also be updated through the testing.accessibility.compliance object in the package.json file. The default is WCAG Level A, but it can be updated to anything listed in the pa11y documentation.

The test file lives in /tests/accessibility/compliance/pa11y.js if any edits are needed (such as staging credentials, if you're running tests in an environment that requires authentication).

Visual Regression Testing

We use BackstopJS to run our visual regression tests. BackstopJS requires just a few settings to work: a scenarios array that tells it which URL's to screenshot, a viewports array that tells it what breakpoints to use, and a config object for global settings.

Begin by setting which URL's you'd like to test in the testing.urls object in package.json. You will see some default URL's (homepage, article, search-results), but you can add as many as you'd like. These URL's are read by tests/visual/scenarios.js to automatically produce the scenarios array that BackstopJS will use to take screenshots.

You can also create custom scenarios in tests/visual/custom-scenarios.js. Custom scenarios allow us to add specific options for specific URL's, for situations like hovering over an element to screenshot its hover state, or clicking a modal button and waiting for the modal to become visible.

To create a custom scenario, simply set the urlName property to match the property name in the testing.urls object, and then create an options object with your desired settings. A couple examples are provided in tests/visual/custom-scenarios.js and you can see a list of all available options in the advanced scenarios section on GitHub.

BackstopJS can take screenshots at various screen widths, so make sure to match the breakpoints in tests/visual/viewports.js with those in your theme.

Though generally not necessary, you can customize the BackstopJS configuration by changing the settings in tests/visual/config.js.

To begin running BackstopJS visual regression tests, initialize its required files. This only needs to be done once on your local machine:

npm run test:visual-init

Then create a set of screenshots that will become the base reference images to run future tests against:

npm run test:visual-reference

After you've made changes and want to test for visual regressions:

npm run test:visual

Finally, if the new screenshots fail but contain desired changes, approve them for use as the new base reference images:

npm run test:visual-approve

Automated Acceptance Testing

Automated acceptance testing in the Theme Scaffolding leverages WP Acceptance and is included in the project via Composer as a dev required package. Run the command composer update (see Composer Commands above) to install the required packages. Refer to the documentation to ensure your host machine has the necessary requirements. The Theme Scaffolding is already setup to work with WP Acceptance and a few example tests have been created to serve as examples.

To run the test suite, from the root of the repository, run ./vendor/bin/wpacceptance run. WP Acceptance will automatically run the test suite in isolated docker containers. To write your own acceptance tests, refer to the documentation and cookbook.

Contributing

We don't know everything! We welcome pull requests and spirited, but respectful, debates. Please contribute via pull requests on GitHub.

Fork it!
Create your feature branch: git checkout -b feature/my-new-feature
Commit your changes: git commit -am 'Added some great feature!'
Push to the branch: git push origin feature/my-new-feature
Submit a pull request

Learn more about the default packages used with this project

Support Level

Active: 10up is actively working on this, and we expect to continue work for the foreseeable future including keeping tested up to the most recent version of WordPress. Bug reports, feature requests, questions, and pull requests are welcome.

10up/theme-scaffold