wordpress-develop README

The project's README from github.com/WordPress/wordpress-develop. As one markdown file: README.md.

WordPress

Welcome to the WordPress development repository! Please check out the contributor handbook for information about how to open bug reports, contribute patches, test changes, write documentation, or get involved in any way you can.

Getting Started

Local development

WordPress is a PHP, MySQL, and JavaScript based project, and uses Node for its JavaScript dependencies. A local development environment is available to quickly get up and running.

You will need a basic understanding of how to use the command line on your computer. This will allow you to set up the local development environment, to start it and stop it when necessary, and to run the tests.

You will need Node and npm installed on your computer. Node is a JavaScript runtime used for developer tooling, and npm is the package manager included with Node. If you have a package manager installed for your operating system, setup can be as straightforward as:

If you are not using a package manager, see the Node.js download page for installers and binaries.

Note: WordPress currently only officially supports Node.js 20.x and npm 10.x.

You will also need a container environment such as Docker Desktop installed and running on your computer. The container environment is the virtualization software that powers the local development environment and can be installed just like any other regular application.

Note: WordPress currently only officially supports Docker but several container environments are available and should generally be compatible, such as Colima, OrbStack, Podman Desktop, and Rancher Desktop.

Development Environment Commands

Ensure your container environment is running before using these commands.

To start the development environment for the first time

You can get started using the local development environment with these steps:

  1. Go to https://github.com/WordPress/wordpress-develop and fork the repository to your own GitHub account.
  2. Then clone the forked repository to your computer using git clone https://github.com/<your-username>/wordpress-develop.git.
  3. Navigate into the directory for the cloned repository using cd wordpress-develop.
  4. Add the origin repo as an upstream remote via git remote add upstream https://github.com/WordPress/wordpress-develop.git.
  5. Then you can keep your branches up to date via git pull --ff upstream trunk, for example.

Alternatively, if you have the GitHub CLI installed, you can simply run gh repo fork WordPress/wordpress-develop --clone (docs). This command will:

  1. Fork the repository to your account (use the --org flag to clone into an organization).
  2. Clone the repository to your machine.
  3. Add WordPress/wordpress-develop as upstream and set it to the default remote repository

After this, remember to run cd wordpress-develop.

Once you have forked and cloned the repository to your computer, run the following commands in a terminal:

npm install
npm run build:dev
npm run env:start
npm run env:install

Your WordPress site will be accessible at http://localhost:8889. You can see or change configurations in the .env file located at the root of the project directory.

To watch for changes

If you're making changes to WordPress core files, you should start the file watcher in order to build or copy the files as necessary:

npm run dev

To stop the watcher, press ctrl+c.

To run a WP-CLI command

npm run env:cli -- <command>

WP-CLI has many useful commands you can use to work on your WordPress site. Where the documentation mentions running wp, run npm run env:cli -- instead. For example:

npm run env:cli -- help

To run the tests

These commands run the PHP and end-to-end test suites, respectively:

npm run test:php
npm run test:e2e

You can pass extra parameters into the PHP tests by adding -- and then the command-line options:

npm run test:php -- --filter <test name>
npm run test:php -- --group <group name or ticket number>

To run the JavaScript (QUnit) tests:

npm run grunt qunit:compiled

qunit:compiled builds first, then runs the suite. The QUnit runner loads scripts from the built build/ directory, so a plain npm run grunt qunit requires a completed npm run build first without a build, every test fails with a jQuery is not defined error.

To lint the workflow files

GitHub Actions workflows operate in a privileged software supply chain environment, therefore all workflow files must adhere to a high degree of quality and security standards.

All YAML workflow files within the .github/workflows directory are statically scanned when modified using Actionlint and Zizmor. It's recommended that you install both of these tools locally using a package manager to run prior to submitting changes to workflow files.

To run Actionlint:

actionlint

To run Zizmor for all workflow files (note the trailing period):

zizmor .

Note: A workflow run failure will not occur when issues are detected by Zizmor. Instead, the generated report is submitted to GitHub Code Scanning and surfaced through a status check. Some locally reported issues may be ignored based on the repository's configured Code Scanning settings.

Generating a code coverage report

PHP code coverage reports are generated daily and submitted to Codecov.io.

After the local container environment has been installed and started, the following command can be used to generate a code coverage report. 

npm run test:coverage

The command will generate three coverage reports in HTML, PHP, and text formats, saving them in the coverage folder.

Note: xDebug is required to generate a code coverage report, which can slow down PHPUnit significantly. Passing selection-based options such as --group or --filter can decrease the overall time required but will result in an incomplete report.

To restart the development environment

You may want to restart the environment if you've made changes to the configuration in the docker-compose.yml or .env files. Restart the environment with:

npm run env:restart

To stop the development environment

You can stop the environment when you're not using it to preserve your computer's power and resources:

npm run env:stop

To start the development environment again

Starting the environment again is a single command:

npm run env:start

Resetting the development environment

The development environment can be reset. This will destroy the database and attempt to remove the pulled container images.

npm run env:reset

Apple Silicon machines and old MySQL/MariaDB versions

Older MySQL and MariaDB container images do not support Apple Silicon processors (M1, M2, etc.). This is true for:

When using these versions on an Apple Silicon machine, you must create a docker-compose.override.yml file with the following contents:

services:

  mysql:
    platform: linux/amd64

Additionally, the "Use Rosetta for x86/AMD64 emulation on Apple Silicon" setting in your container environment (if applicable) needs to be disabled for this workaround.

Credentials

These are the default environment credentials:

To login to the site, navigate to http://localhost:8889/wp-admin.

Note: With Codespaces, open the portforwarded URL from the ports tab in the terminal, and append /wp-admin to login to the site.

To generate a new password (recommended):

  1. Go to the Dashboard
  2. Click the Users menu on the left
  3. Click the Edit link below the admin user
  4. Scroll down and click 'Generate password'. Either use this password (recommended) or change it, then click 'Update User'. If you use the generated password be sure to save it somewhere (password manager, etc).

wordpress-develop (WordPress/wordpress-develop)

Searching Database…

3.5K ·GitHub
Wordpress-develop
Что это такое?Официальный репозиторий разработки WordPress: исходный код ядра WordPress, хранящийся как Git-зеркало subversion-репозитория WordPress. Он нужен для работы над самим WordPress, а не для установки блога.
Это тот WordPress, который ставят на сайт, или код, на котором он работает?Это исходный код: проект на PHP, MySQL и JavaScript, где Node используется для JavaScript-зависимостей. Вы разрабатываете и тестируете этот код локально; обычные пользователи устанавливают готовые релизы WordPress.
Как поднять локальный сайт WordPress для разработки из этого репозитория?Установите Node и npm, а также окружение контейнеров, например Docker Desktop, сделайте форк и склонируйте репозиторий, затем запустите команды поднятия окружения из README. После этого сайт будет доступен по локальному адресу, а настройки лежат в файле .env в корне проекта.
Какие версии Node и Docker мне нужны?Официально поддерживается только Node.js 20.x с npm 10.x. Docker — официально поддерживаемое окружение контейнеров, но Colima, OrbStack, Podman Desktop и Rancher Desktop тоже, как правило, работают.
Есть ли известные подводные камни, например на Mac с Apple Silicon?Да: старые образы контейнеров MySQL (5.7 и старше) и MariaDB 5.5 не запускаются на Apple Silicon (M1, M2). Потребуется обходной путь через docker-compose.override.yml и нужно отключить настройку эмуляции x86/AMD64 через Rosetta.
Окружение для разработки работает на Windows и Linux или только на macOS?На всех трёх. В README есть команды установки для macOS (brew), Windows (choco) и Ubuntu (apt), а само окружение запускается в контейнерах на любой из этих систем.
Как запустить тесты?npm-скрипты запускают наборы PHP- и end-to-end-тестов, а qunit:compiled — тесты на JavaScript. Сначала нужно собрать проект: раннер QUnit загружается из каталога build/, и без завершённой сборки каждый тест падает с ошибкой jQuery is not defined.
Какие учётные данные по умолчанию у локального сайта для разработки?Войдите в локальный wp-admin с логином admin и паролем password. База данных — wordpressdevelop с пользователем root и паролем password; в README рекомендуется сгенерировать новый пароль администратора через админ-панель (Dashboard).
Можно ли использовать WP-CLI в этом окружении?Да. Там, где в документации WordPress сказано выполнить wp, в этом окружении для разработки нужно вместо этого запускать npm run env:cli --.
What are similar projects?woocommerce, WordPress, wp-calypso, gutenberg, Neofollower-SMM-Reseller-API-for-Woocommerce, angular-webpack-starter, caprover, typecho
Which topics is it in?blogging, wordpress, cms, unit-testing, gplv2, php, github-actions, mysql, apple-silicon, testing, docker-compose, web-development
Creator
WordPress
Size
386.1 MB
Stars
3.5K
Updated
CommitOct 17
Age
9y
Commits · 90 Days