WordPress.org Block Theme

A block-based child theme for WordPress.org, plus local environment.

Once set up, this environment will contain some shared plugins (Jetpack, Gutenberg, etc), some mu-plugins (wporg-mu-plugins, mu-plugins/pub), and both sets of parent and child themes. The current site uses wporg parent and wporg-main child; while the new design will be done with wporg-parent-2021 and wporg-main-2022 (this repo). The "theme-switcher" in mu-plugins here should control which theme is used, based on the requested page.

Development

Prerequisites

• Docker
• Node/npm
• Yarn
• Composer

Setup

1. Set up repo dependencies.

   yarn setup:tools

2. Start the local environment.

   yarn wp-env start

3. Run the setup script.

   yarn setup:wp

4. Build the theme.

   yarn workspaces run build

5. (optional) There may be times when you want to make changes to the Parent theme and test them with the Main them. To do that:

   1. Clone the Parent repo and follow the setup instructions in its readme.md file.
   2. Create a .wp-env.override.json file in this repo
   3. Copy the themes section from .wp-env.json and paste it into the override file. You must copy the entire section for it to work, because it won't be merged with .wp-env.json.
   4. Update the path to the Parent theme to the Parent theme folder inside the Parent repository you cloned above.

   {
       "themes": [
   	    "./source/wp-content/themes/wporg",
   	    "./source/wp-content/themes/wporg-main",
   	    "./source/wp-content/themes/wporg-main-2022",
   	    "../wporg-parent-2021/source/wp-content/themes/wporg-parent-2021"
       ]
   }

6. Visit site at localhost:8888.

7. Log in with username admin and password password.

Environment management

These must be run in the project's root folder, not in theme/plugin subfolders.

• Stop the environment.

  yarn wp-env stop

• Restart the environment.

  yarn wp-env start

• Build the theme's JavaScript

  yarn workspace wporg-main-2022-theme build

  or, automatically build on changes:

  yarn workspace wporg-main-2022-theme start

• Refresh local WordPress content with a current copy from the staging site.

  yarn setup:refresh

• Reset WordPress to a clean install, and reconfigure. This will nuke all local WordPress content!

  yarn wp-env clean all
  yarn setup:wp

• SSH into docker container.

  yarn wp-env run wordpress bash

• Run wp-cli commands. Keep the wp-cli command in quotes so that the flags are passed correctly.

  yarn wp-env run cli "post list --post_status=publish"

• Update composer dependencies and sync any repo-tools changes.

  yarn update:tools

• Run a lighthouse test.

  yarn lighthouse

• Check visual diffs.

Backstopjs can be manually run to create reference snapshots and then check for visual differences.

```bash
yarn backstop:reference
# change something in the code or content
yarn backstop:test
```

Building Patterns from Page Content

1. Run the generator script:
   1. If you're using the Docker environment, start Docker and run yarn wp-env start. Then run yarn build:patterns.
   2. If you're using a local environment, cd env and run wp eval-file export-content/index.php page-manifest.json directly.
2. Verify git stat and git diff look right
3. git add and git commit
4. Sync to SVN and deploy like you would any other commit