Skip to content

Latest commit

 

History

History
452 lines (277 loc) · 21.6 KB

development-environment.md

File metadata and controls

452 lines (277 loc) · 21.6 KB
Raw

Development Environment

Table of contents

Setting up your environment

Overview

In order to start developing the Jetpack plugin you want to have access to a WordPress installation where you can install the plugin and work on it.

To do that you need to set up a WordPress site and give it the ability to run your local build of the Jetpack plugin code repository.

There are several ways to achieve this, listed in the next section.

Running Jetpack locally

To get a local WordPress site up and running you need a web server (Apache, Nginx), PHP and MySQL (or MariaDB).

Important: Docker is the only solution that we recommend and can provide support for. The others are listed here as reference if you want to try something different. We won't be able to provide support for them

  • Docker (Supported Recommended)

    This would be the easiest and most straight-forward way to start your journey in Jetpack development. Docker offers a containerized install of WordPress with all of its dependencies installed and set up. You just need to start working on the plugin code.

    To set up your environment with Docker, follow the Docker environment for Jetpack Development guide.

  • VVV

    VVV is similar to Docker in how it works, but instead of setting up separate containers for the different parts it uses a single Linux virtual machine to set everything up with a nice interface.

    You can read up more about setting up VVV on the project's official page.

  • Local web and database servers

    This is the most involved set up way among the three. Since the installation steps are very dependent on the operating system and it's flavor, we're not going to cover them here for the time being. You can refer to the WordPress recommended system requirements to see what you need to install to get WordPress up and running on your system.

  • Developing and contributing code to Jetpack from a Windows machine

    When working on a Windows machine, you will need to use Windows Subsystem for Linux version 2. If you are currently using WSL version 1, you will need to update to version 2 first.

    If you use VS Code, you can use their Remote Development extension pack to develop in WSL.

    You may, however, run into issues when you want to commit your changes. In this case, and if you use an IDE like PHPStorm, you can follow the recommendations in this post to have PhpStorm Use Windows Subsystem For Linux’s Git.

Get started with development

Here are the different steps you must follow to set up your Jetpack development environment:

  1. Clone the repository
  2. Install development tools
  3. Check if your environment is ready for Jetpack development

Clone the repository

Before you get started, we recommend that you set up a public SSH key setup with GitHub, which is more secure than saving your GitHub credentials in your keychain. There are more details about setting up a public key on GitHub.com.

Fork this repository to your own GitHub account and clone it to your local machine, as explained in this guide. If you are an Automattician, you can clone the repository directly.

If you use our Docker setup, you can now move on to the next step.

If you are not using a Docker setup, you'll first need to create symlinks from the plugin directory in your local installation of WordPress to each of the plugins' directories in the monorepo (under projects/plugins/).

Note that the Monorepo should not be cloned into the WordPress plugins directory (you will see a warning on your plugins page in that case saying that the Jetpack Monorepo is not a plugin and shouldn't be installed as one).

Install development tools

You'll need all the tools below to work in the Jetpack monorepo.

  • Node.js

    Node.js is used in the build process of some of our tools. If it's not already installed on your system, you can visit the Node.js website and install the latest Long Term Support (LTS) version.

    You'll find the minimum required version in the engines section of package.json.

    We recommend usage of nvm for managing different Node versions on the same environment.

  • Pnpm

    Pnpm is a Node.js package manager and it's used to install packages that are required to run development tools and build projects. To install it, either run npm install -g pnpm or you can visit the Installation page of the project for other methods.

    You'll find the minimum required version in the engines section of package.json.

  • PHP

    PHP is a popular general-purpose scripting language that is especially suited to web development and it's at the core of the WordPress ecosystem.

    If you use our Docker setup, PHP will be available to you in the container.

    If you use a different setup, you'll need to install PHP on your operating system. As it's very dependent on your operating system and its flavor, we're not going to cover it in this document at this time. You can check out the official installation instructions from the project website.

  • Composer

    Composer is a PHP package manager and it's used to install packages that are required to run development tools and build projects.

    The monorepo requires version 2.3.x.

    • Installing Composer on macOS

      Composer can be installed using Homebrew. If you don't have Homebrew, install it with

      /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

      And then install Composer:

      brew install composer
    • Installing Composer on other systems

      We recommend visiting the official Composer download instructions to install composer on other operating systems.

      Most Linux distributions may have an older version of Composer as an installable package, but installing from the official source ensures you have the most up to date version. Note that we recommend using the Windows Subsystem for Linux to run Composer and PHP.

  • jetpack CLI

    The jetpack CLI tool is used to help with development in the Jetpack monorepo. Find out more and install it by following the instructions on the Jetpack CLI page.

Check if your environment is ready for Jetpack development

We provide a script to help you in assessing if everything's ready on your system to contribute to Jetpack.

tools/check-development-environment.sh

Running the script will tell you if you have your environment already set up and what you need to do in order to get it ready for Jetpack development.

If you're ready to start, you should see all green SUCCESS messages. If the script detect issues, you will see a red FAILED note and a link that will help you figure out what you need to change/fix to address the issue.

Once you're all set here, you can continue developing. If you're setting up an local environment and want to start testing immediately, please ensure you build the projects you need.

jetpack build will provide prompts to determine the project you need or you can pass it a complete command, like jetpack build plugins/jetpack --deps

Testing Jetpack cloud features

In order to test features that require a WordPress.com connection and other network related Jetpack features, you'll need a test site that can create local HTTP tunnels.

If you're an Automattician, we recommend using Jurassic Tube.

For other methods, check out ngrok or another similar service.

Development workflow

Once you have a local copy of Jetpack and all development tools installed, you can start developing.

  1. Make sure the plugin you're developing is activated on your WordPress site.
  2. Build your project
  3. Access the plugin's dashboard in your browser.

Building your project

The Jetpack monorepo is home to different projects, with different needs. Some require that you build PHP, JavaScript, and CSS components. The Jetpack CLI tool will help you with all building steps.

There are different types of builds:

  • Development build

    A standard development build will create un-minified versions of the JavaScript and CSS files. To build a project, run:

     jetpack build

    The Jetpack CLI tool will then guide you so you can build the project you are interested in.

  • Continuous Development build

    By default the development build above will run once and if you change any of the files, you need to run jetpack build again to see the changes on the site. If you want to avoid that, you can run a continuous build that will rebuild anytime it sees any changes on your local filesystem. To run it, use:

     jetpack watch

  • Draft Mode

    This is an experimental feature as of August 2021.

    Are pre-commit and pre-push hooks slowing down a major refactor or draft PR? Run jetpack draft enable to make them less aggressive (they will still run, but won't block for warnings), and jetpack draft disable when you're ready for them again.

Syncing local changes with Unison

In some cases, you may need to test Jetpack (jetpack-mu-wpcom, in particular) changes by syncing your changes to another machine (rather than using Docker). This outlines a strategy for syncing changes in real-time using the Unison file sync tool combined with the unison-fsmonitor (Note that unison-fsmonitor is OSX-only).

This approach may be especially useful for Automatticians who are testing changes on their WordPress.com sandbox. Using Unison can be more continuous than rsync (or jetpack rsync).

Installing Unison

Please see the respective Unison and unison-fsmonitor repositories for full installation instructions.

On OSX, you can use Homebrew to quickly install both tools:

  • brew install unison autozimu/formulas/unison-fsmonitor

Configuring Unison

Once Unison is installed, you'll want to create a preferences file. On OSX/Linux, that preferences file would be placed in ~/.unison and could be called something like jetpack-plugin-sync.prf. See the Unison documentation for instructions for other platforms.

The built-in Unison help documentation may be useful:

  • unison -doc tutorial | less
  • unison -doc basics | less
  • unison -doc running | less

Here is a sample preferences file. Please note that this example preferences file is set to always prefer local changes over remote changes. You'll need to adjust the file if you require a two-way sync instead. See the Unison documentation (or run unison -doc running | less) for full configuration details.

Running Unison

Once your preference file is configured, you can simply run something like the following in a terminal:

unison -ui text -repeat watch jetpack-plugin-sync

Unison will watch for any local changes to the Jetpack files and sync them to your remote host.

Unit-testing

The Jetpack plugin includes several unit tests that you can run in your local environment before submitting a new Pull Request.

If you're not familiar with PHP Unit Testing, you can also check this tutorial

To get started, there are several ways to run the unit tests, depending on how you set up your development environment.

PHP unit tests

⚠️ This section is in need of update! Changes to how WordPress sets up its tests mean that a global version of phpunit is no longer provided.

  • Docker

    To run the PHP unit tests for Jetpack if you're running Docker, you can run the following:

     jetpack docker phpunit

    This will run unit tests for Jetpack. You can pass arguments to phpunit like so:

     jetpack docker phpunit -- --filter=Protect

    This command runs the tests as a multi site install

     jetpack docker phpunit-multisite -- --filter=Protect

    To run tests for specific packages, you can run the tests locally, from within the package's directory:

     cd projects/packages/assets
 composer phpunit

  • VVV & Local Installs

    If you are running a recent version of VVV then Jetpack will automatically detect your wordpress-develop install and you can just run phpunit directly.

    Otherwise you'll need to manually install the wordpress-develop branch, as follows:

     svn co https://develop.svn.wordpress.org/trunk/ /tmp/wordpress-develop
 cd /tmp/wordpress-develop
 cp wp-tests-config-sample.php wp-tests-config.php

    Set the database information for your testing DB in the file /tmp/wordpress-develop/wp-tests-config.php. You may need to create this database.

    To run tests on your machine, you can run phpunit while in the Jetpack directory.

    To run WooCommerce integration tests, you'll need the WooCommerce plugin installed alongside Jetpack (in ../woocommerce), and you can run:

     JETPACK_TEST_WOOCOMMERCE=1 phpunit

    To run multisite tests, run:

     phpunit -c tests/php.multisite.xml

    To filter and run just a particular test, you can run:

     phpunit --filter my_test_name

JavaScript unit tests

Jetpack includes also several Jest based unit tests. To execute them in your local environment, you can use the following commands.

  • Admin Page unit tests

    Standing on your jetpack directory, run

     pnpm install
 pnpm test-client
 pnpm test-gui

  • Jetpack modules unit tests

    Standing on your jetpack directory, run

     pnpm install
 pnpm test-modules

    You can also only run tests matching a specific pattern. To do that, use the argument -g, --grep <pattern>:

     pnpm test-gui -g 'my custom pattern to filter tests'

    To use a custom reporter, pass the argument -R, --reporter <name>:

     pnpm test-client -R 'my_reporter'

Good code - linting, standards, compatibility, etc.

Coding standards

We strongly recommend that you install tools to review your code in your IDE. It will make it easier for you to notice any missing documentation or coding standards you should respect. Most IDEs display warnings and notices inside the editor, making it even easier.

  • Jetpack's custom Code Sniffer ruleset is located at ./projects/packages/codesniffer/Jetpack/ruleset.xml. Depending on your IDE, you can use this path or you may need to use .phpcs.xml.dist in the monorepo root.
  • For JavaScript, we recommend installing ESLint. Most IDEs come with an ESLint plugin that you can use. Jetpack includes a eslint.config.mjs file that defines our coding standards.

Linting

  • Linting Jetpack's PHP code

    You can easily run these commands to set up all the rulesets and then lint Jetpack's PHP code. You need Composer to run this tool so check how to install Composer if you don't have it yet.

    This will install all the CodeSniffer rulesets we need for linting Jetpack's PHP code. You may need to do this only once.

     composer install

    This runs the actual linting task.

     composer phpcs:lint

  • Checking Jetpack's PHP for compatibility with different versions of PHP

    We have a handy composer script that will just run the PHP CodeSniffer PHPCompatibilityWP ruleset checking for code not compatible with supported PHP versions:

     composer phpcs:compatibility

  • Linting Jetpack's JavaScript

    pnpm lint will check syntax and style in the following JavaScript pieces:

    • All the front end JavaScript that Jetpack relies on.
    • All the JavaScript present in the Admin Page Single Page App for Jetpack.
     pnpm lint

    If you haven't done it yet, you may need to run pnpm install before pnpm lint for installing node modules for this task.

Standard development & debugging tools

  • WP_DEBUG

    You should do all Jetpack development with define( 'WP_DEBUG', true ); in your wp-config.php, making sure that you’re not generating any Notices or other PHP issues in your error_log.

  • SCRIPT_DEBUG

    By default, WordPress loads minified versions of Jetpack's JS files. If you want to work with them, add define( 'SCRIPT_DEBUG', true ); in your wp-config.php. This tells WordPress to load the non-minified JS version, allowing you to see your changes on page refresh. This applies to the JS files outside of _inc/client/ and extensions/.

  • WP-CLI

    Jetpack CLI is a command line interface for Jetpack, extending off of WP-CLI for WordPress. You can easily modify your installation of Jetpack with a just a few simple commands. All you need is SSH access and a basic understanding of command line tools.

    Usage:

    • wp jetpack status [<full>]
    • wp jetpack module <list|activate|deactivate|toggle> [<module_name>]
    • wp jetpack options <list|get|delete|update> [<option_name>] [<option_value>]
    • wp jetpack protect <allow> [<ip|ip_low-ip_high|list|clear>]
    • wp jetpack reset <modules|options>
    • wp jetpack disconnect <blog|user> [<user_identifier>]
    • wp jetpack status
    • wp jetpack status [<full>]

    More info can be found in our support documentation.

  • JETPACK_DEV_DEBUG

    JETPACK_DEV_DEBUG constant can be used to enable offline mode in Jetpack. Add define( 'JETPACK_DEV_DEBUG', true ); in your wp-config.php to enable it. With Offline Mode, features that do not require a connection to WordPress.com servers can be activated on a local WordPress installation for testing.

    Offline mode automatically gets enabled if you don’t have a period in your site’s hostname, i.e. localhost. If you use a different URL, such as mycooltestsite.local, then you will need to define the JETPACK_DEV_DEBUG constant.

    You can also enable Jetpack’s offline mode through a plugin, thanks to the jetpack_offline_mode filter:

    add_filter( 'jetpack_offline_mode', '__return_true' );

    While in Offline Mode, some features will not be available at all as they require WordPress.com for all functionality—Related Posts and Jetpack Social, for example. Other features will have reduced functionality to give developers a good-faith representation of the feature. For example, Tiled Galleries requires the WordPress.com Photon CDN; however, in Offline Mode, Jetpack provides a fallback so developers can have a similar experience during development and testing. Find out more in our support documentation.

  • JETPACK__SANDBOX_DOMAIN

    External contributors do not need this constant. If you’re working on changes to the WordPress.com/server side of Jetpack, you’ll need to instruct your Jetpack installation to talk to your development server. Refer to internal documentation for detailed instructions.