From 09fa4a1170988d3f2bf33dde5eeb7663b910b6f5 Mon Sep 17 00:00:00 2001 From: Elio Rivero Date: Wed, 5 Jun 2019 12:50:43 -0300 Subject: [PATCH 1/6] Add instructions on package installation and usage --- packages/README.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 packages/README.md diff --git a/packages/README.md b/packages/README.md new file mode 100644 index 000000000000..c94f3ed98340 --- /dev/null +++ b/packages/README.md @@ -0,0 +1,73 @@ +# Jetpack packages for Development + +These Composer packages offer a unified codebase that we will share among projects under the Jetpack brand. + +## Installing Composer + +Composer can be installed using [Homebrew](https://brew.sh/). If you still 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 +``` + +## 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(); +``` From c91ab19b23a0be0113897f75d1e4f9f29044bd76 Mon Sep 17 00:00:00 2001 From: Elio Rivero Date: Wed, 5 Jun 2019 14:30:42 -0300 Subject: [PATCH 2/6] Move content about installing Composer to the doc regarding development environment. Add a pointer to that section in the packages' readme --- docs/development-environment.md | 20 +++++++++++++++++++- packages/README.md | 13 +------------ 2 files changed, 20 insertions(+), 13 deletions(-) diff --git a/docs/development-environment.md b/docs/development-environment.md index 6ac1a3e0530c..b72c8e9e22a1 100644 --- a/docs/development-environment.md +++ b/docs/development-environment.md @@ -157,6 +157,24 @@ 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 this packages in Jetpack itself or other projects, you need Composer, the PHP package manager. + +It's also necessary to use the PHP CodeSniffer that ensures your code follows code standards. + +Composer can be installed using [Homebrew](https://brew.sh/). If you still 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 +``` + ## 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 +184,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 index c94f3ed98340..73a96d848a54 100644 --- a/packages/README.md +++ b/packages/README.md @@ -4,18 +4,7 @@ These Composer packages offer a unified codebase that we will share among projec ## Installing Composer -Composer can be installed using [Homebrew](https://brew.sh/). If you still 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 -``` +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 From 1d2153c9d1f97afa5620fe2ca503ebdfd7561b82 Mon Sep 17 00:00:00 2001 From: Elio Rivero Date: Wed, 5 Jun 2019 14:39:18 -0300 Subject: [PATCH 3/6] Explain how to install Composer on systems other than macOS. Props @aldavigdis --- docs/development-environment.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/development-environment.md b/docs/development-environment.md index b72c8e9e22a1..06b8581c1f42 100644 --- a/docs/development-environment.md +++ b/docs/development-environment.md @@ -163,6 +163,8 @@ Jetpack includes a number of packages such as the `jetpack-logo` and to use this 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 still don't have Homebrew, install it with ``` @@ -175,6 +177,13 @@ 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 than macOS. + +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 do recommend using the Windows Subsystem for Linux 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. From f9547b36e74a7180eeb229e332bec10ee8fcc863 Mon Sep 17 00:00:00 2001 From: Elio Rivero Date: Wed, 5 Jun 2019 16:57:03 -0300 Subject: [PATCH 4/6] Update docs/development-environment.md Co-Authored-By: Jeremy Herve --- docs/development-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development-environment.md b/docs/development-environment.md index 06b8581c1f42..1fbec6f1a00c 100644 --- a/docs/development-environment.md +++ b/docs/development-environment.md @@ -159,7 +159,7 @@ $ yarn test-client -R 'my_reporter' ## Installing Composer -Jetpack includes a number of packages such as the `jetpack-logo` and to use this packages in Jetpack itself or other projects, you need Composer, the PHP package manager. +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. From 1f38edb26f2656ff22e4f95d08d79d85e43c9be5 Mon Sep 17 00:00:00 2001 From: Elio Rivero Date: Wed, 5 Jun 2019 16:58:01 -0300 Subject: [PATCH 5/6] Apply suggestions from code review Co-Authored-By: Jeremy Herve --- docs/development-environment.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/development-environment.md b/docs/development-environment.md index 1fbec6f1a00c..f7f14e5c66f0 100644 --- a/docs/development-environment.md +++ b/docs/development-environment.md @@ -165,7 +165,7 @@ It's also necessary to use the PHP CodeSniffer that ensures your code follows co ### Installing Composer on macOS -Composer can be installed using [Homebrew](https://brew.sh/). If you still don't have Homebrew, install it with +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)" @@ -179,10 +179,10 @@ 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 than macOS. +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 do recommend using the Windows Subsystem for Linux to run composer and PHP. +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 From b0f2212731fb397a7d611c0315e68f2fd1343c5b Mon Sep 17 00:00:00 2001 From: Elio Rivero Date: Wed, 5 Jun 2019 17:09:43 -0300 Subject: [PATCH 6/6] Add reference to Composer installation in the section that explains how to start developing for Jetpack --- docs/development-environment.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/development-environment.md b/docs/development-environment.md index 06b8581c1f42..cb3f0dce4234 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