diff --git a/docs/development-environment.md b/docs/development-environment.md index 6ac1a3e0530c..5466613e270a 100644 --- a/docs/development-environment.md +++ b/docs/development-environment.md @@ -46,9 +46,10 @@ $ yarn distclean $ cd jetpack ``` -3. Install yarn. Please, refer to yarn's [Installation Documentation](https://yarnpkg.com/docs/install/). +3. [Install Composer](#installing-composer). +4. Install Yarn. Please, refer to Yarn's [Installation Documentation](https://yarnpkg.com/docs/install/). -4. Make sure the Jetpack plugin is active and run +5. Make sure the Jetpack plugin is active and run ``` $ yarn build @@ -56,7 +57,7 @@ $ yarn distclean This will install npm dependencies and then build the files. -5. Open `/wp-admin/admin.php?page=jetpack` in your browser. +6. Open `/wp-admin/admin.php?page=jetpack` in your browser. ## Development build @@ -157,6 +158,33 @@ To use a custom reporter, pass the argument `-R, --reporter `: $ yarn test-client -R 'my_reporter' ``` +## Installing Composer + +Jetpack includes a number of packages such as the `jetpack-logo` and to use these packages you need Composer, the PHP package manager. + +It's also necessary to use the PHP CodeSniffer that ensures your code follows code standards. + +### Installing Composer on macOS + +Composer can be installed using [Homebrew](https://brew.sh/). If you don't have Homebrew, install it with + +``` +/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" +``` + +And then install Composer: + +``` +brew install composer +``` + +### Installing Composer on other systems + +We recommend visiting the [official Composer download instructions](https://getcomposer.org/download/) 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](#developing-and-contributing-code-to-jetpack-from-a-windows-machine) to run Composer and PHP. + ## Use PHP CodeSniffer and ESLint to make sure your code respects 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. @@ -166,7 +194,7 @@ We strongly recommend that you install tools to review your code in your IDE. It ### Linting Jetpack's PHP -You can easily run these commands to set up all the rulesets and then lint 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](#installing-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. diff --git a/packages/README.md b/packages/README.md new file mode 100644 index 000000000000..73a96d848a54 --- /dev/null +++ b/packages/README.md @@ -0,0 +1,62 @@ +# Jetpack packages for Development + +These Composer packages offer a unified codebase that we will share among projects under the Jetpack brand. + +## Installing Composer + +You need Composer to use the packages. If you don't have it installed, go and check how to [install Composer](https://github.com/Automattic/jetpack/blob/master/docs/development-environment.md#installing-composer) and then continue here. + +## Defining required packages + +You need to create a `composer.json` file in your project root. For example, this is the file in VaultPress that requires the Jetpack logo package. + +```json +{ + "name": "automattic/vaultpress", + "description": "VaultPress is a subscription service offering real-time backup, automated security scanning, and support from WordPress experts.", + "homepage": "https://vaultpress.com/", + "type": "wordpress-plugin", + "license": "GPL-2.0-or-later", + "support": { + "issues": "https://github.com/Automattic/vaultpress/issues" + }, + "require": { + "automattic/jetpack-logo": "1.0.0" + }, + "require-dev": { + "automattic/jetpack-standards": "master-dev" + } +} +``` + +## Installing packages + +Once you have defined your package requirements, run + +``` +composer install +``` + +and that will install the required Composer packages. + +### Using packages + +To use something from a package, you have to declare it at the top of the file before any other instruction, and then use it in the code. For example, the logo can be used like this: + +```php +use Automattic\Jetpack\Assets\Logo; + +// other code... + +$logo = new Logo(); +``` + +If you need to rule out conflicts, you can alias it: + +```php +use Automattic\Jetpack\Assets\Jetpack_Logo; + +// other code... + +$logo = new Jetpack_Logo(); +```