# Automattic's Free Themes

### Coding Standards

Themes code should adhere to the [WordPress coding standards](https://make.wordpress.org/core/handbook/best-practices/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 i` 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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-prettier-config/) which can (optionally) be used in your IDE or command-line to format your code via (Prettier)[https://prettier.io/docs/en/editors.html].

## Deploying to WordPress.com

Once you have merged your PR, you can deploy the theme to WordPress.com by running `npm run deploy` from the root of this repository.

There are more detailed docs for deploying themes [here](https://wp.me/PNEWy-eqL).

## Packaging for WordPress.org Themes Showcase

The code in this repository is for the theme to function correctly on _WordPress.com_. To prepare a theme.zip that passes the _WordPress.org_ theme review automated test, do the following:

- From the top-level directory, run `.theme-utils/package-dotorg.sh [theme-slug]`
- View the generated zip in the respective theme's sub-directory

Note that this script rebuilds the theme to strip it of .com-specific functionality, and discards any changes via git after doing so. _Make sure you have committed any working changes before running this script._

## 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. See the Field Guide or Theme Dev P2.

### Commands

Command | Description | Args
--- | --- | ---
`npm run batch:audit:fix` | Audits and fixes dependencies for all the themes. | None
`npm run batch:build` | Builds all the themes (runs `npm run build` on each of them). | None
`npm run batch:build-blockbase-children` | Builds all blockbase children (runs `npm run build` on each of them). | None
`npm run batch:install` | Install node dependencies for all the themes. | None
`npm run batch:update` | Update node dependencies for all themes | None
`npm run changelog:rebuild` | Rebuild the entire changelog from the given starting hash. | `<theme-slug> <since>`
`npm run changelog:update` | Use the commit log to build a list of recent changes and add them as a new changelog entry. If add-changes is true, the updated readme.txt will be staged. | `<theme-slug> <add-changes, true/false>`
`npm run core:checkout` | Use SVN to checkout the given core themes from the wpcom SVN repository. | `<theme-slug>`
`npm run core:create-pr` | Given a theme slug and specific revision create a GitHub pull request from the resources currently on the sandbox. | `<theme-slug> <since-revision>`
`npm run core:pull` | Use rsync to copy all public Core theme files from your sandbox to your local machine. Core themes are any of the Twenty<whatever> themes. | None
`npm run core:push` | Use rsync to copy all public Core theme files from your local machine to your sandbox. Core themes are any of the Twenty<whatever> themes. | None
`npm run core:sync` | Given a theme slug and SVN revision, sync the theme from the specified revision to the latest. This requires the Core theme to be currently checked out from the wpcom svn repository. | `<theme-slug> <since-revision>`
`npm run deploy` | Version bumps all changed themes since the last deployment <br/> Cleans and updates the sandbox<br/> Pushes all changed files (including removing deleted files) since the last deployment<br/> After pausing to allow testing, commits the version bump change to github.a8c.com<br/> Creates a tag in the github.a8c.com repository to mark the deployment<br/>The flag ` -- --skip-strict-types` can be added to skip the strict types check. | None
`npm run deploy:check-strict-typing` | Checks strict typing to any changed themes. | None
`npm run deploy:core:sync` | Given a theme slug and SVN revision, sync the theme from the specified revision to the latest. This command contains additional prompts and error checking not provided by sync-core-theme. | `<theme-slug> <since-revision>`
`npm run deploy:preview` | Display a list of the changes to be deployed. | None
`npm run deploy:push:all` | Uses rsync to copy all modified files for all themes from the local machine to your sandbox with the exclusion of files noted in .sandbox-ignore | None
`npm run deploy:push:changes` | Uses rsync to copy all modified files for any modified themes from the local machine to your sandbox. | None
`npm run deploy:push:theme` | Uses rsync to copy all modified files for the specified theme from the local machine to your sandbox. | `<theme-slug>`
`npm run deploy:theme` | This runs "deploy pub <theme>" on the provided list of themes. | `<array of theme slugs>`
`npm run deploy:test` | This does a test run of `npm run deploy`. Version bumps and changelog updates will be committed to the current branch. No changes will be deployed. | None
`npm run deploy:version-bump` | Bump the version of any theme that has had changes since the last deployment. This includes bumping the version of any parent themes and updating the changelog for the theme. Optionally specify a single theme to version bump. | None
`npm run deploy:version-bump-from-last-bump` | Bump the version of any theme that has had changes since the last "Version Bump" commit. This includes updating the changelog for the theme. Optionally specify a single theme to version bump. | None
`npm run deploy:zip` | Build the production zip file for the specified theme. | `<theme-slug>`
`npm run help` | Returns a list of available commands | None
`npm run local:clean` | Cleans the sandbox of changes | None
`npm run package:dotorg` | Build the .org zip file for the specified theme. | `<theme-slug>`
`npm run patterns:escape` | Escapes block patterns for pattern files that have changes (staged or unstaged). | `[directory]`
`npm run pull:all` | Use rsync to copy all public theme files from your sandbox to your local machine. | None
`npm run sandbox:clean` | Perform a hard reset, checkout trunk, and pull wpcom-themes on your sandbox. | None
`npm run validate:theme` | Validates a theme against the WordPress theme requirements. | None