Working on a sandbox

Read this page before you do anything on a sandbox. Every rule below is a way to affect production by accident.

Ground rules

1. A sandbox is not sandboxed from the database or the cache. You have full access to production data, and anything you write is written for real. There is no reset button.
2. Always develop using must-use plugins. Regular plugins write their activation state to the production wp_options table; must-use plugins do not. Put your work-in-progress in mu-plugins/ and it stays invisible to production.
3. Sandboxes cannot save attachments. Do not attempt to upload media. De-sandbox yourself first and do it as a normal user.
4. DeployingDeploy Launching code from a local development environment to the production web server, so that it’s available to visitors. deploys all code, not just your changes. See Deploying WordPress.org — this one surprises people, and it is the most expensive mistake on this list.
5. Always test before deploying. The automated pre-deployDeploy Launching code from a local development environment to the production web server, so that it’s available to visitors. checks are a safety net, not a substitute for looking at the thing you changed.
6. Do not deploy at the end of your day and disappear. If it breaks, you are the person who needs to be there.

What the environment gives you

Sandboxes ship with a small toolset. You can try installing things yourself, or go to https://make.wordpress.org/systems/ to request something that is missing (see example).

You can install tools into your own home directory without a system request. For WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/:

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
./wp-cli.phar --info

WordCamp.org already has a wrapper, so there is nothing to install for that web root — run bin/wp-cli/wp from /home/wordcamp/public_html.

For anything that needs to be installed system-wide, file a system request — see Requesting sandbox access.

Scale

WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ is a large multisiteMultisite Multisite is a WordPress feature which allows users to create a network of sites on a single WordPress installation. Available since WordPress version 3.0, Multisite is a continuation of WPMU or WordPress Multiuser project. WordPress MultiUser project was discontinued and its features were included into WordPress core. Advanced Administration Handbook -> Create A Network. — several hundred sites. Two consequences:

• find across the web root is impractical. Scope your searches to a specific pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party., theme, or mu-plugins directory.
• WP-CLI commands need a --url. Without one you will act on the wrong site.

wp --url=https://wordpress.org/plugins/ plugin list

To search every web root at once without walking into SVNSVN Apache Subversion (often abbreviated SVN, after its command name svn) is a software versioning and revision control system. Software developers use Subversion to maintain current and historical versions of files such as source code, web pages, and documentation. Its goal is to be a mostly compatible successor to the widely used Concurrent Versions System (CVS). WordPress core and the wordpress.org released code are all centrally managed through SVN. https://subversion.apache.org/. and GitGit Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/ checkouts, uploads, or dependency trees, prune them first:

find /home -type d \( \
  -name .git -o \
  -name .svn -o \
  -name node_modules -o \
  -name blogs.dir -o \
  -name .npm \
\) -prune -o -type f -name '<filename>' -print

Logging

A sandbox does not print anything to your terminal when you load a page in a browser. Use error_log() or trigger_error() and read the log, rather than expecting output.

Granting roles for testing

You do not need to find an administrator to raise someone’s role so they can smoke test a wp-admin screen. From a sandbox you can do it yourself with WP-CLI:

cd /home/wordcamp/public_html
bin/wp-cli/wp user add-role <username> editor --url=https://central.wordcamp.org

This is a real change to production. A sandbox shares the production database, so the role is genuinely granted — it is not scoped to your session or your sandbox. Remove it again once the testing is done:

bin/wp-cli/wp user remove-role <username> editor --url=https://central.wordcamp.org

The same code lives in more than one place

Some code is shared across the WordPress.org network and is checked out into several web roots. wporg-sso is the clearest example — it is maintained in WordPress/wordpress.org under common/includes/wporg-sso/, and is loaded from at least:

• /home/wporg/public_html/wp-content/mu-plugins/wporg-sso
• /home/wordcamp/public_html/wp-content/mu-plugins-private/wporg-mu-plugins/wporg-sso
• BuddyPress, via wp-content/mu-plugins/wporg-sso.php

/home/wordcamp/public_html/wp-content/mu-plugins-private$ svn proplist .
Properties on '.':
  svn:externals
  svn:ignore
/home/wordcamp/public_html/wp-content/mu-plugins-private$ svn propget svn:externals .
wporg-mu-plugins	https://dotorg.svn.wordpress.org/wordpress/website/wp-content/mu-plugins
wporg-sso		https://meta.svn.wordpress.org/sites/trunk/common/includes/wporg-sso

If you change shared code, you have to deploy every site that loads it. Patching one web root and not the others ships a partial fix. Before you deploy, check which roots reference the file you touched.

The wporg-mu-plugins external above is built from WordPress/wporg-mu-plugins on GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. https://github.com/ and synced into dotorg.svn — see Shared mu-plugins for how to get a merged PR from there onto the sandbox.

Configuration is shared the same way. /home/wporg/public_html/.config/ and /home/wordcamp/public_html/.config/ are working copies of the same dotorg.svn path, so a change committed from either one lands in both — and has to be deployedDeploy Launching code from a local development environment to the production web server, so that it’s available to visitors. to both.

When you are not sure whether two paths are really the same external, compare their repository URLs:

svn info --show-item url /home/wporg/public_html/.config/
svn info --show-item url /home/wordcamp/public_html/.config/

Identical output means one checkout in two places. See Shared configuration for how to deploy a change to it.

Repositories with no GitHub counterpart

Not everything is on GitHub. Some sites — profiles.wordpress.org under /home/buddypress/public_html/, for instance — are edited on the sandbox directly.

For those, it is often easier to sync a copy down to your machine, work locally with your normal editor and tooling, and push it back:

# sandbox -> local
rsync -avz --exclude='.svn' --exclude='.git' \
	wporgsandbox:/home/buddypress/public_html/wp-content/ .

# local -> sandbox
rsync -avz --exclude='.svn' --exclude='.git' \
	. wporgsandbox:/home/buddypress/public_html/wp-content/

Excluding .svn and .git keeps you from clobbering the working copy’s metadata. You still commit from the sandbox.

Site-specific notes

• jobs.wordpress.net runs on a cPanel host. It has no WordPress.org users and carries local modifications that are in neither SVN nor Git. Ask in #meta before changing anything there.
• api.wordpress.org should carry only high-request, high-throughput endpoints for coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and WordPress.org. Anything else belongs in a wp-json endpoint in the relevant repository.

Is there a GitHub repo for this?

Many WordPress.org components are developed on GitHub and synced into SVN, but not all of them, and it is not always obvious which. If you are about to commit to dotorg.svn, check the history first:

svn log <path> | head -30

If the most recent commit message is a Sync, the canonical source is a GitHub repository and you should go through the GitHub workflow instead of committing directly.