themes-wordpress/CONTRIBUTING.md

Guide to Contributing Code

The following guide will help you through the process of contributing code to the themes repo.

By contributing code to our free themes, you grant its use under the GNU General Public License v2 (or later).

Prerequisites

Our repo is a monorepo which stores all the themes maintained by the Automattic Theme Team. We use Node.js to run utility functions from the top-level directory, and also to run commands for some themes, such as building the CSS files. We are currently using Node version 16.

We recommend using the Node Version Manager (nvm) since it is the easiest way to install and manage Node for macOS, Linux, and Windows 10. See the Node.js site for additional installation instructions.

Also make sure you have an updated version of git installed on your computer, as well as a GitHub account.

Local Environment Setup

We recommend setting up a local WordPress environment to test any changes.

You can use the wp-env package for setting up a WordPress environment locally. You'll need to install Docker to use wp-env.

As an alternative to Docker setup, you can use Local, WampServer, or MAMP, or even use a remote server.

Local Themes Setup

Clone the repo locally and then install the dependencies:

$ git clone git@github.com:Automattic/themes.git
$ cd themes
$ npm install

Coding Standards

Themes code should adhere to the WordPress coding standards. This repo contains a pre-commit hook which enables you to detect and fix code that doesn't follow the standards.

To set this up follow these instructions:

1. Run npm install in the root of the repo.
2. Run composer install

Now when you commit changes to a file PHPCBF will attempt to fix any issues with the file.

This will also install the WordPress-standard Prettier Configuration which can (optionally) be used in your IDE or command-line to format your code via Prettier.

Browser Support

We support the same browsers as WordPress Core, listed here.

Contributing CSS

A great way to get started with contributing to our themes is to pick up a CSS fix or patch.

A lot of our themes use SASS for styling, and then use Node to compile the final CSS. Usually, these themes will have a sass directory (example), and there will also be a package.json file at the root of the theme (example).

In order to change the styles in these themes, you need to edit the SASS file first, and then run a build command to compile the CSS. Here is the process in most cases, using Varia as an example:

1. Change to the theme's directory cd varia
2. Find the .scss file you need to edit in the sass directory
3. Make your changes
4. Run the build command using npm run build
5. You should see your updates in the newly built .css file/s

If you are unsure what to do, leave us a comment so that we can improve documentation for other themes that may work differently.

Best Practices

We use the latest features from the CSS, HTML and JS specifications, where our browser support will allow it. Caniuse.com is a great way to check if a feature is supported.

We use intrinsic web design in our themes where possible. Every Layout is a good resource for this.

Workflow

Here is a quick summary of our workflow:

1. Create a pull request with your changes
2. Request a review of your PR
3. The Themes Team will provide feedback or approve your PR
4. The team will merge and deploy your PR (to both .com and .org)

Creating a pull request

When your changes are ready for review you should create a pull request. Here are a couple tips for crafting a great pull request:

• Include the purpose of your PR. Be explicit about the idea or issue your PR solves.
• Reference any existing issues that relate to your PR. This allows everyone to easily see all related discussions.

The Themes Team will be notified when a new pull request is opened and we triage new issues and PRs regularly. Another good way to request a review is to add the team as Reviewers to your PR using the team handle, @Automattic/theam.

Once your PR has been approved, the Themes Team will merge and deploy your change to both .com and .org. Please note that merging a PR does not automatically deploy a change.

Deployments

The easiest way to deploy a change is to let the Themes Team handle it! This is because not everyone has a sandbox or the appropriate commit rights to handle a deployment.

Deploying changes is part of the team's daily processes. We try to deploy approved changes as soon as possible, often multiple times a day. Please leave a comment if you have any questions or you want us to trigger a deploy.

Triggering a deployment

If you have a sandbox and have the correct commit rights, you can use one of our sandbox tools to trigger your own deployment.

From the top-level directory, run npm run deploy and follow the prompts. Please make sure to test your changes on your sandbox before completing the deployment.

Sandbox Tools

If you use a sandbox to test or develop your themes you can use a couple of utilities to operate on that sandbox.

• From the top-level directory, run node ./theme-utils.mjs clean-sandbox to bring the public themes GIT repository to a clean state. (This will only matter if your sandbox uses GIT such as how WordPress.com is currently managed.) Alternately you can trigger that as an npm script: npm run sandbox:clean. npm run sandbox:clean-all will clean the entire sandbox.

• From the top-level directory, run node ./theme-utils.mjs push-to-sandbox to push your entire working copy to the public themes folder of your sandbox. Alternately you can trigger this as an npm script: npm run deploy:push:all This command will rsync your local copy with the exception of anything in the .sandbox-ignore file. You should clean your sandbox before pushing any changes to it. node ./theme-utils.mjs push-changes-to-sandbox or npm run deploy:push:changes alternatively will push only files that have changed since the last deployment.