diff --git a/README.md b/README.md index 7a079e7..412e05c 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ A library for Opt-in and Telemetry data to be sent to the StellarWP Telemetry se - [Table of Contents](#table-of-contents) - [Installation](#installation) - [Usage Prerequisites](#usage-prerequisites) + - [Filters \& Actions](#filters--actions) - [Integration](#integration) - [Uninstall Hook](#uninstall-hook) - [Opt-In Modal Usage](#opt-in-modal-usage) @@ -14,30 +15,9 @@ A library for Opt-in and Telemetry data to be sent to the StellarWP Telemetry se - [Saving Opt-In Status on a Settings Page](#saving-opt-in-status-on-a-settings-page) - [How to Migrate Users Who Have Already Opted In](#how-to-migrate-users-who-have-already-opted-in) - [Utilizing a Shared Telemetry Instance](#utilizing-a-shared-telemetry-instance) - - [Filter Reference](#filter-reference) - - [stellarwp/telemetry/{hook-prefix}/should\_show\_optin](#stellarwptelemetryhook-prefixshould_show_optin) - - [stellarwp/telemetry/{hook-prefix}/option\_name](#stellarwptelemetryhook-prefixoption_name) - - [stellarwp/telemetry/{hook-prefix}/optin\_status](#stellarwptelemetryhook-prefixoptin_status) - - [stellarwp/telemetry/{hook-prefix}/optin\_status\_label](#stellarwptelemetryhook-prefixoptin_status_label) - - [stellarwp/telemetry/optin\_args](#stellarwptelemetryoptin_args) - - [stellarwp/telemetry/{stellar\_slug}/optin\_args](#stellarwptelemetrystellar_slugoptin_args) - - [stellarwp/telemetry/{hook-prefix}/show\_optin\_option\_name](#stellarwptelemetryhook-prefixshow_optin_option_name) - - [stellarwp/telemetry/{hook-prefix}/register\_site\_url](#stellarwptelemetryhook-prefixregister_site_url) - - [stellarwp/telemetry/{hook-prefix}/register\_site\_data](#stellarwptelemetryhook-prefixregister_site_data) - - [stellarwp/telemetry/{hook-prefix}/register\_site\_user\_details](#stellarwptelemetryhook-prefixregister_site_user_details) - - [stellarwp/telemetry/{hook-prefix}/send\_data\_args](#stellarwptelemetryhook-prefixsend_data_args) - - [stellarwp/telemetry/{hook-prefix}/send\_data\_url](#stellarwptelemetryhook-prefixsend_data_url) - - [stellarwp/telemetry/{hook-prefix}/last\_send\_expire\_seconds](#stellarwptelemetryhook-prefixlast_send_expire_seconds) - - [stellarwp/telemetry/exit\_interview\_args](#stellarwptelemetryexit_interview_args) - - [stellarwp/telemetry/{stellar\_slug}/exit\_interview\_args](#stellarwptelemetrystellar_slugexit_interview_args) - - [stellarwp/telemetry/{hook-prefix}/event\_data](#stellarwptelemetryhook-prefixevent_data) - - [stellarwp/telemetry/{hook-prefix}/events\_url](#stellarwptelemetryhook-prefixevents_url) - - [Action Reference](#action-reference) - - [stellarwp/telemetry/optin](#stellarwptelemetryoptin) - - [stellarwp/telemetry/{hook-prefix}/optin](#stellarwptelemetryhook-prefixoptin) - - [stellarwp/telemetry/{hook-prefix}/event](#stellarwptelemetryhook-prefixevent) - [Adding Plugin Data to Site Health](#adding-plugin-data-to-site-health) - [Capturing User Events](#capturing-user-events) + - [Contribution](#contribution) ## Installation It's recommended that you install Telemetry as a project dependency via [Composer](https://getcomposer.org/): @@ -52,10 +32,12 @@ composer require stellarwp/telemetry > Luckily, adding Strauss to your `composer.json` is only slightly more complicated than adding a typical dependency, so checkout our [strauss docs](https://github.com/stellarwp/global-docs/blob/main/docs/strauss-setup.md). ## Usage Prerequisites -To actually _use_ the telemetry library, you must have a Dependency Injection Container (DI Container) that is compatible with [di52](https://github.com/lucatume/di52) (_We recommend using di52_). +To actually _use_ the telemetry library, you must have a Dependency Injection Container (DI Container) that is compatible with the [StellarWP Container Contract](https://github.com/stellarwp/container-contract). -In order to keep this library as light as possible, a container is not included in the library itself. To avoid version compatibility issues, it is also not included as a Composer dependency. Instead, you must include it in your project. We recommend including it via composer [using Strauss](https://github.com/stellarwp/global-docs/blob/main/docs/strauss-setup.md), just like you have done with this library. +In order to keep this library as light as possible, a container is not included in the library itself, however we do recommend [di52](https://github.com/lucatume/di52). To avoid version compatibility issues, it is also not included as a Composer dependency. Instead, you must include it in your project. We recommend including it via composer [using Strauss](https://github.com/stellarwp/global-docs/blob/main/docs/strauss-setup.md), just like you have done with this library. +## Filters & Actions +If you'd like to take a look at the existing filters & actions available through the library, [view that documentation here](docs/filters.md). ## Integration Initialize the library within your main plugin file after plugins are loaded (or anywhere else you see fit). You can configure a unique prefix (we suggest you use your plugin slug) so that hooks can be uniquely called for your specific instance of the library. @@ -127,7 +109,10 @@ When a user deletes the plugin, WordPress runs the method from `Uninstall` and c ## Opt-In Modal Usage +![The default modal shown to users that have not dismissed it yet.](docs/img/default-opt-in-modal.png) + ### Prompting Users on a Settings Page + On each settings page you'd like to prompt the user to opt-in, add a `do_action()`. _Be sure to include your defined stellar\_slug_. ```php do_action( 'stellarwp/telemetry/optin', '{stellar_slug}' ); @@ -232,212 +217,6 @@ function add_plugin_to_telemetry() { } ``` -## Filter Reference - -If you configured this library to use a hook prefix, note that all hooks will now use this prefix. For example: -```php -add_filter( 'stellarwp/telemetry/my-custom-prefix/should_show_optin', 'my-custom-filter', 10, 1 ); -``` -### stellarwp/telemetry/{hook-prefix}/should_show_optin -Filters whether the user should be shown the opt-in modal. - -**Parameters**: _bool_ `$should_show` - -**Default**: `true` - -### stellarwp/telemetry/{hook-prefix}/option_name -Filter the option name used to store current users' optin status. - -**Parameters**: _string_ `$option_name` - -**Default**: `stellarwp_telemetry` - -### stellarwp/telemetry/{hook-prefix}/optin_status -Filter the optin status of the current site. - -**Parameters**: _integer_ `$status` - -**Default**: `1` - -Each status corresponds with an integer: -```php -1 = 'Active', -2 = 'Inactive', -3 = 'Mixed', -``` -### stellarwp/telemetry/{hook-prefix}/optin_status_label -Filter the label used to show the current opt-in status of the site. - -**Parameters**: _string_ `$optin_label` - -**Default**: see: [stellarwp/telemetry/optin_status](#stellarwptelemetryoptin_status) -### stellarwp/telemetry/optin_args -Filter the arguments passed to the opt-in modal. - -**Parameters**: _array_ `$args`, _string_ `$stellar_slug` - -**Default**: -```php -$args = [ - 'plugin_logo' => Resources::get_asset_path() . 'resources/images/stellar-logo.svg', - 'plugin_logo_width' => 151, - 'plugin_logo_height' => 32, - 'plugin_logo_alt' => 'StellarWP Logo', - 'plugin_name' => 'The Events Calendar', - 'plugin_slug' => $stellar_slug, - 'user_name' => wp_get_current_user()->display_name, - 'permissions_url' => '#', - 'tos_url' => '#', - 'privacy_url' => '#', - 'opted_in_plugins_text' => __( 'See which plugins you have opted in to tracking for', 'stellarwp-telemetry' ), - 'heading' => __( 'We hope you love {plugin_name}.', 'stellarwp-telemetry' ), - 'intro' => __( 'Hi, {user_name}.! This is an invitation to help our StellarWP community. If you opt-in, some data about your usage of {plugin_name} and future StellarWP Products will be shared with our teams (so they can work their butts off to improve). We will also share some helpful info on WordPress, and our products from time to time. And if you skip this, that’s okay! Our products still work just fine.', 'stellarwp-telemetry' ), -]; -``` -### stellarwp/telemetry/{stellar_slug}/optin_args -This filter will be deprecated in future versions. Use [stellarwp/telemetry/optin_args](#stellarwptelemetrystellar_slugoptin_args) instead. - -### stellarwp/telemetry/{hook-prefix}/show_optin_option_name -Filters the string used for the option that determines whether the opt-in modal should be shown. - -**Parameters**: _string_ `$option_name` - -**Default**: `stellarwp_telemetry_{plugin_slug}_show_optin` -### stellarwp/telemetry/{hook-prefix}/register_site_url -Filters the url of the telemetry server that will store the site data when registering a new site. - -**Parameters**: _string_ `$url` - -**Default**: `https://telemetry.example.com/api/v1/register-site` -### stellarwp/telemetry/{hook-prefix}/register_site_data -Filters the data that is sent to the telemetry server when registering a new site. - -**Parameters**: _array_ `$site_data` - -**Default**: -```php -$site_data = [ - 'telemetry' => json_encode( $this->provider->get_data() ), -]; -``` -### stellarwp/telemetry/{hook-prefix}/register_site_user_details -Filters the user details that is sent to the telemetry server when registering a new site. - -**Parameters**: _array_ `$user_details` - -**Default**: -```php -$user_details = [ - 'name' => $user->display_name, - 'email' => $user->user_email, - 'plugin_slug' => Config::get_container()->get( Core::PLUGIN_SLUG ), -]; -``` -### stellarwp/telemetry/{hook-prefix}/send_data_args - -**Parameters**: _array_ $data_args - -**Default**: -```php -$data_args = [ - 'token' => $this->get_token(), - 'telemetry' => json_encode( $this->provider->get_data() ), -]; -``` - -### stellarwp/telemetry/{hook-prefix}/send_data_url -Filters the full url to use when sending data to the telemetry server. - -**Parameters**: _string_ `$url` - -**Default**: `https://telemetry.example.com/api/v1/telemetry` - -### stellarwp/telemetry/{hook-prefix}/last_send_expire_seconds -Filters how often the library should send site health data to the telemetry server. - -**Parameters**: _integer_ `$seconds` - -**Default**: `7 * DAY_IN_SECONDS` - -### stellarwp/telemetry/exit_interview_args -Filters the arguments used in the plugin deactivation "exit interview" form. - -**Parameters**: _array_ `$args`, _string_ `$stellar_slug` - -**Default**: -```php -$args = [ - 'plugin_slug' => $stellar_slug, - 'plugin_logo' => plugin_dir_url( __DIR__ ) . 'public/logo.png', - 'plugin_logo_width' => 151, - 'plugin_logo_height' => 32, - 'plugin_logo_alt' => 'StellarWP Logo', - 'heading' => __( 'We’re sorry to see you go.', 'stellarwp-telemetry' ), - 'intro' => __( 'We’d love to know why you’re leaving so we can improve our plugin.', 'stellarwp-telemetry' ), - 'questions' => [ - [ - 'question' => __( 'I couldn’t understand how to make it work.', 'stellarwp-telemetry' ), - 'show_field' => true - ], - [ - 'question' => __( 'I found a better plugin.', 'stellarwp-telemetry' ), - 'show_field' => true - ], - [ - 'question' => __( 'I need a specific feature it doesn’t provide.', 'stellarwp-telemetry' ), - 'show_field' => true - ], - [ - 'question' => __( 'The plugin doesn’t work.', 'stellarwp-telemetry' ), - 'show_field' => true - ], - [ - 'question' => __( 'It’s not what I was looking for.', 'stellarwp-telemetry' ), - 'show_field' => true - ] - ], -]; -``` - -### stellarwp/telemetry/{stellar_slug}/exit_interview_args -This filter will be deprecated in future versions. Use [stellarwp/telemetry/exit_interview_args](#stellarwptelemetrystellar_slugexit_interview_args) instead. - -### stellarwp/telemetry/{hook-prefix}/event_data -Filters the array of data sent along with the event. - -**Parameters**: _array_ `$data` - -**Default**: -```php -$data = [ - 'token' => $this->telemetry->get_token(), - 'stellar_slug' => Config::get_stellar_slug(), - 'event' => $name, - 'event_data' => wp_json_encode( $data ), -]; -``` -### stellarwp/telemetry/{hook-prefix}/events_url -Filters the event URL used when sending events to the Telemetry server. - -**Parameters**: _string_ `$url` - -**Default**: `https://telemetry.stellarwp.com/api/v1/events` - -## Action Reference - -### stellarwp/telemetry/optin - -**Parameters**: _string_ `$stellar_slug` The stellar slug of the plugin for which the modal should be shown. -### stellarwp/telemetry/{hook-prefix}/optin -This filter will be deprecated in future versions. Use [stellarwp/telemetry/optin](#stellarwptelemetryoptin) instead. - -### stellarwp/telemetry/{hook-prefix}/event -Sends a site event to the Telemetry server. - -**Parameters**: -- _string_ `$event` The name of the event. -- _array_ `$data` A set of data that should be passed along with the event. - ## Adding Plugin Data to Site Health We collect the Site Health data as json on the server. In order to pass additional plugin specific items that can be reported on, you will need to add a section to the Site Health Data. The process for adding a section is documented on [developer.wordpress.org](https://developer.wordpress.org/reference/hooks/debug_information/). @@ -535,3 +314,10 @@ function user_creates_post( $post_id, $post, $update ) { do_action( 'stellarwp/telemetry/{hook-prefix}/event', 'new_post', $event_data ); } ``` + +## Contribution + +There are more detailed docs that provide guidance on contributing to the library: +- [Automated testing](/docs/automated-testing.md) +- [Local Environment Configuration](/docs/local-environment.md) +- [Quality Assurance](/docs/quality-assurance.md) diff --git a/docs/filters.md b/docs/filters.md new file mode 100644 index 0000000..f444e58 --- /dev/null +++ b/docs/filters.md @@ -0,0 +1,230 @@ +# Filter Reference + +## Table of Contents +- [Filter Reference](#filter-reference) + - [Table of Contents](#table-of-contents) + - [stellarwp/telemetry/{hook-prefix}/should\_show\_optin](#stellarwptelemetryhook-prefixshould_show_optin) + - [stellarwp/telemetry/{hook-prefix}/option\_name](#stellarwptelemetryhook-prefixoption_name) + - [stellarwp/telemetry/{hook-prefix}/optin\_status](#stellarwptelemetryhook-prefixoptin_status) + - [stellarwp/telemetry/{hook-prefix}/optin\_status\_label](#stellarwptelemetryhook-prefixoptin_status_label) + - [stellarwp/telemetry/optin\_args](#stellarwptelemetryoptin_args) + - [stellarwp/telemetry/{stellar\_slug}/optin\_args](#stellarwptelemetrystellar_slugoptin_args) + - [stellarwp/telemetry/{hook-prefix}/show\_optin\_option\_name](#stellarwptelemetryhook-prefixshow_optin_option_name) + - [stellarwp/telemetry/{hook-prefix}/register\_site\_url](#stellarwptelemetryhook-prefixregister_site_url) + - [stellarwp/telemetry/{hook-prefix}/register\_site\_data](#stellarwptelemetryhook-prefixregister_site_data) + - [stellarwp/telemetry/{hook-prefix}/register\_site\_user\_details](#stellarwptelemetryhook-prefixregister_site_user_details) + - [stellarwp/telemetry/{hook-prefix}/send\_data\_args](#stellarwptelemetryhook-prefixsend_data_args) + - [stellarwp/telemetry/{hook-prefix}/send\_data\_url](#stellarwptelemetryhook-prefixsend_data_url) + - [stellarwp/telemetry/{hook-prefix}/last\_send\_expire\_seconds](#stellarwptelemetryhook-prefixlast_send_expire_seconds) + - [stellarwp/telemetry/exit\_interview\_args](#stellarwptelemetryexit_interview_args) + - [stellarwp/telemetry/{stellar\_slug}/exit\_interview\_args](#stellarwptelemetrystellar_slugexit_interview_args) + - [stellarwp/telemetry/{hook-prefix}/event\_data](#stellarwptelemetryhook-prefixevent_data) + - [stellarwp/telemetry/{hook-prefix}/events\_url](#stellarwptelemetryhook-prefixevents_url) + - [Action Reference](#action-reference) + - [stellarwp/telemetry/optin](#stellarwptelemetryoptin) + - [stellarwp/telemetry/{hook-prefix}/optin](#stellarwptelemetryhook-prefixoptin) + - [stellarwp/telemetry/{hook-prefix}/event](#stellarwptelemetryhook-prefixevent) + +If you configured this library to use a hook prefix, note that all hooks will now use this prefix. For example: +```php +add_filter( 'stellarwp/telemetry/my-custom-prefix/should_show_optin', 'my-custom-filter', 10, 1 ); +``` +### stellarwp/telemetry/{hook-prefix}/should_show_optin +Filters whether the user should be shown the opt-in modal. + +**Parameters**: _bool_ `$should_show` + +**Default**: `true` + +### stellarwp/telemetry/{hook-prefix}/option_name +Filter the option name used to store current users' optin status. + +**Parameters**: _string_ `$option_name` + +**Default**: `stellarwp_telemetry` + +### stellarwp/telemetry/{hook-prefix}/optin_status +Filter the optin status of the current site. + +**Parameters**: _integer_ `$status` + +**Default**: `1` + +Each status corresponds with an integer: +```php +1 = 'Active', +2 = 'Inactive', +3 = 'Mixed', +``` +### stellarwp/telemetry/{hook-prefix}/optin_status_label +Filter the label used to show the current opt-in status of the site. + +**Parameters**: _string_ `$optin_label` + +**Default**: see: [stellarwp/telemetry/optin_status](#stellarwptelemetryoptin_status) +### stellarwp/telemetry/optin_args +Filter the arguments passed to the opt-in modal. + +**Parameters**: _array_ `$args`, _string_ `$stellar_slug` + +**Default**: +```php +$args = [ + 'plugin_logo' => Resources::get_asset_path() . 'resources/images/stellar-logo.svg', + 'plugin_logo_width' => 151, + 'plugin_logo_height' => 32, + 'plugin_logo_alt' => 'StellarWP Logo', + 'plugin_name' => 'The Events Calendar', + 'plugin_slug' => $stellar_slug, + 'user_name' => wp_get_current_user()->display_name, + 'permissions_url' => '#', + 'tos_url' => '#', + 'privacy_url' => '#', + 'opted_in_plugins_text' => __( 'See which plugins you have opted in to tracking for', 'stellarwp-telemetry' ), + 'heading' => __( 'We hope you love {plugin_name}.', 'stellarwp-telemetry' ), + 'intro' => __( 'Hi, {user_name}.! This is an invitation to help our StellarWP community. If you opt-in, some data about your usage of {plugin_name} and future StellarWP Products will be shared with our teams (so they can work their butts off to improve). We will also share some helpful info on WordPress, and our products from time to time. And if you skip this, that’s okay! Our products still work just fine.', 'stellarwp-telemetry' ), +]; +``` +### stellarwp/telemetry/{stellar_slug}/optin_args +This filter will be deprecated in future versions. Use [stellarwp/telemetry/optin_args](#stellarwptelemetrystellar_slugoptin_args) instead. + +### stellarwp/telemetry/{hook-prefix}/show_optin_option_name +Filters the string used for the option that determines whether the opt-in modal should be shown. + +**Parameters**: _string_ `$option_name` + +**Default**: `stellarwp_telemetry_{plugin_slug}_show_optin` +### stellarwp/telemetry/{hook-prefix}/register_site_url +Filters the url of the telemetry server that will store the site data when registering a new site. + +**Parameters**: _string_ `$url` + +**Default**: `https://telemetry.example.com/api/v1/register-site` +### stellarwp/telemetry/{hook-prefix}/register_site_data +Filters the data that is sent to the telemetry server when registering a new site. + +**Parameters**: _array_ `$site_data` + +**Default**: +```php +$site_data = [ + 'telemetry' => json_encode( $this->provider->get_data() ), +]; +``` +### stellarwp/telemetry/{hook-prefix}/register_site_user_details +Filters the user details that is sent to the telemetry server when registering a new site. + +**Parameters**: _array_ `$user_details` + +**Default**: +```php +$user_details = [ + 'name' => $user->display_name, + 'email' => $user->user_email, + 'plugin_slug' => Config::get_container()->get( Core::PLUGIN_SLUG ), +]; +``` +### stellarwp/telemetry/{hook-prefix}/send_data_args + +**Parameters**: _array_ $data_args + +**Default**: +```php +$data_args = [ + 'token' => $this->get_token(), + 'telemetry' => json_encode( $this->provider->get_data() ), +]; +``` + +### stellarwp/telemetry/{hook-prefix}/send_data_url +Filters the full url to use when sending data to the telemetry server. + +**Parameters**: _string_ `$url` + +**Default**: `https://telemetry.example.com/api/v1/telemetry` + +### stellarwp/telemetry/{hook-prefix}/last_send_expire_seconds +Filters how often the library should send site health data to the telemetry server. + +**Parameters**: _integer_ `$seconds` + +**Default**: `7 * DAY_IN_SECONDS` + +### stellarwp/telemetry/exit_interview_args +Filters the arguments used in the plugin deactivation "exit interview" form. + +**Parameters**: _array_ `$args`, _string_ `$stellar_slug` + +**Default**: +```php +$args = [ + 'plugin_slug' => $stellar_slug, + 'plugin_logo' => plugin_dir_url( __DIR__ ) . 'public/logo.png', + 'plugin_logo_width' => 151, + 'plugin_logo_height' => 32, + 'plugin_logo_alt' => 'StellarWP Logo', + 'heading' => __( 'We’re sorry to see you go.', 'stellarwp-telemetry' ), + 'intro' => __( 'We’d love to know why you’re leaving so we can improve our plugin.', 'stellarwp-telemetry' ), + 'questions' => [ + [ + 'question' => __( 'I couldn’t understand how to make it work.', 'stellarwp-telemetry' ), + 'show_field' => true + ], + [ + 'question' => __( 'I found a better plugin.', 'stellarwp-telemetry' ), + 'show_field' => true + ], + [ + 'question' => __( 'I need a specific feature it doesn’t provide.', 'stellarwp-telemetry' ), + 'show_field' => true + ], + [ + 'question' => __( 'The plugin doesn’t work.', 'stellarwp-telemetry' ), + 'show_field' => true + ], + [ + 'question' => __( 'It’s not what I was looking for.', 'stellarwp-telemetry' ), + 'show_field' => true + ] + ], +]; +``` + +### stellarwp/telemetry/{stellar_slug}/exit_interview_args +This filter will be deprecated in future versions. Use [stellarwp/telemetry/exit_interview_args](#stellarwptelemetrystellar_slugexit_interview_args) instead. + +### stellarwp/telemetry/{hook-prefix}/event_data +Filters the array of data sent along with the event. + +**Parameters**: _array_ `$data` + +**Default**: +```php +$data = [ + 'token' => $this->telemetry->get_token(), + 'stellar_slug' => Config::get_stellar_slug(), + 'event' => $name, + 'event_data' => wp_json_encode( $data ), +]; +``` +### stellarwp/telemetry/{hook-prefix}/events_url +Filters the event URL used when sending events to the Telemetry server. + +**Parameters**: _string_ `$url` + +**Default**: `https://telemetry.stellarwp.com/api/v1/events` + +## Action Reference + +### stellarwp/telemetry/optin + +**Parameters**: _string_ `$stellar_slug` The stellar slug of the plugin for which the modal should be shown. +### stellarwp/telemetry/{hook-prefix}/optin +This filter will be deprecated in future versions. Use [stellarwp/telemetry/optin](#stellarwptelemetryoptin) instead. + +### stellarwp/telemetry/{hook-prefix}/event +Sends a site event to the Telemetry server. + +**Parameters**: +- _string_ `$event` The name of the event. +- _array_ `$data` A set of data that should be passed along with the event. diff --git a/docs/img/default-opt-in-modal.png b/docs/img/default-opt-in-modal.png new file mode 100644 index 0000000..dc20f15 Binary files /dev/null and b/docs/img/default-opt-in-modal.png differ diff --git a/docs/img/telemetry-test-plugin.png b/docs/img/telemetry-test-plugin.png new file mode 100644 index 0000000..7900a7f Binary files /dev/null and b/docs/img/telemetry-test-plugin.png differ diff --git a/docs/local-environment.md b/docs/local-environment.md index fc391d3..70338f1 100644 --- a/docs/local-environment.md +++ b/docs/local-environment.md @@ -11,7 +11,9 @@ Once lando starts, you should have a fresh environment running at [https://telem A newly created local environment -This environment has a default plugin that does only what's required to load and initialize the library. Currently, the opt-in modal loads on every admin page for ease of use. If you need to test the library more, download and configure the [Telemetry Starter Plugin](https://github.com/stellarwp/telemetry-starter). +This environment has a default plugin that provides several tools to test the different aspects of the library. As features are added, the plugin should be updated with features to test new functionality. + +![The local plugin used to test all functionality related to the library](img/telemetry-test-plugin.png) ## Xdebug with VS Code diff --git a/docs/quality-assurance.md b/docs/quality-assurance.md new file mode 100644 index 0000000..6ea6e92 --- /dev/null +++ b/docs/quality-assurance.md @@ -0,0 +1,27 @@ +# Quality Assurance Process + +Throughout the development of the library, new features and bug fixes will need to be tested. + +## Prerequisites + +You will need to install the `dist-archive` WP CLI command to create a plugin zip that QA technicians can install in various WordPress environments. + +```sh +lando wp package install wp-cli/dist-archive-command +``` + +The `dist-archive` command provides production ready zips of plugin directories. [Learn More](https://developer.wordpress.org/cli/commands/dist-archive/) + +## QA Preparation Process + +*\*Assuming all relevant branches have been code reviewed and approved* +1. Deploy the [Server](https://github.com/stellarwp/telemetry-server) branch to the development environment and tag it with “Pending QA” +2. Push the feature branch for the Library to the repository and tag it with “Pending QA” +3. Set up any necessary functionality within the Library’s lando environment that’s necessary to validate the new feature (this should take place during feature development as a normal process) +4. Update the version number of the plugin in the environment following normal semantic versioning +5. Export the plugin as a zip with Lando: +```sh +lando wp dist-archive dev/public/wp-content/plugins/library-testing +``` +6. Set up necessary Postman requests and parameters for export that QA can import and use to test the [Server](https://github.com/stellarwp/telemetry-server) changes +7. Upload Postman export and generated plugin zip from step 5 diff --git a/docs/readme.md b/docs/readme.md index 684eccb..18f188f 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -2,3 +2,4 @@ 1. [Automated testing](/docs/automated-testing.md) 2. [Local Environment Configuration](/docs/local-environment.md) +3. [Quality Assurance](/docs/quality-assurance.md)