diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 52ac2df1a..5bdb83709 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -18,6 +18,8 @@ We follow [Semantic Versioning](https://semver.org/). - In `wp-convertkit.php`, change the Version header to the new version number. - In `wp-convertkit.php`, change the `CONVERTKIT_PLUGIN_VERSION` constant to the new version number. +- In `readme.txt`, change the `Stable tag` to the new version number. This is the version wordpress.org serves to users, so it must be updated. +- In `readme.txt`, change `Tested up to` if this release has been tested against a newer WordPress version. ## Update the Plugin's readme.txt Changelog @@ -32,7 +34,7 @@ Provide meaningful, verbose updates to the Changelog, in the following format: Generic changelog items such as `Fix: Various bugfixes` or `Several edge-case bug fixes` should be avoided. They don't tell users (or us, as developers) what took place in this version. -Each line in the changelog should start with `Added`, `Fix` or `Updated`. +Each line in the changelog should start with `Added`, `Fix`, `Updated` or `Removed`. ## Generate Localization File and Action/Filter Documentation @@ -54,7 +56,7 @@ Commit the updated files, which should comprise of: ## Submit Release -Once your test(s) are written and successfully run locally, submit your branch via a new [Pull Request](https://github.com/ConvertKit/convertkit-wordpress/compare). +Submit your release branch via a new [Pull Request](https://github.com/ConvertKit/convertkit-wordpress/compare). It's best to create a Pull Request in draft mode, as this will trigger all tests to run as a GitHub Action, allowing you to double check all tests pass. diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index ab973bbd7..c19fb3f45 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -66,7 +66,7 @@ Run `npm run watch:css` to compile frontend CSS to `resources/frontend/css/front ### JS -Run `npm run watch:js` to compile frontend JS to `resources/frontend/js/dist/frontend-min.js` when working on JS in the `resources/frontend/js` folder. +Run `npm run watch:js` to compile frontend JS to `resources/frontend/js/dist/frontend.min.js` when working on JS in the `resources/frontend/js` folder. ### Build @@ -84,6 +84,23 @@ If the build process fails, review the terminal and make applicable changes: GitHub actions will run this step for you on testing and deployment, but it's a useful command in development if you need a single command to cover CSS + JS. +## Before Committing + +GitHub Actions runs the following checks on every Pull Request. Running them locally first avoids a round trip: + +| Command | Checks | +|---------|--------| +| `composer php-coding-standards` | PHP Coding Standards on Plugin files (`phpcs.xml`) | +| `composer php-coding-standards-on-tests` | PHP Coding Standards on test files (`phpcs.tests.xml`) | +| `composer css-coding-standards` | CSS / SCSS Coding Standards | +| `composer js-coding-standards` | JS Coding Standards | +| `composer php-static-analysis` | PHPStan static analysis | +| `composer test` | End to End tests | +| `composer test-integration` | Integration tests | + +`composer fix-php-coding-standards`, `fix-css-coding-standards` and `fix-js-coding-standards` will automatically correct many +Coding Standards errors. Refer to the [Testing Guide](TESTING.md) for detail on each. + ## Committing Work Remember to commit your changes to your branch relatively frequently, with a meaningful, short summary that explains what the change(s) do. diff --git a/README.md b/README.md index c5434d1b6..e1fe24a2c 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ For Kit Developers, there are guides covering: - [Development](DEVELOPMENT.md) - best practices for development - [Testing](TESTING.md) - how to write and run tests - [Actions and Filters](ACTIONS-FILTERS.md) - Actions and Filters available to WordPress Developers looking to extend Kit's functionality +- [Security](SECURITY.md) - how to report a security vulnerability For Kit, there is a separate guide to deploying new versions to wordpress.org: - [Deployment](DEPLOYMENT.md) - how to deploy a new Plugin version to [WordPress.org](https://wordpress.org/plugins/convertkit/) \ No newline at end of file diff --git a/SETUP.md b/SETUP.md index f91c16056..450077579 100644 --- a/SETUP.md +++ b/SETUP.md @@ -65,9 +65,11 @@ The Kit Plugin (and/or its Addons) provides integrations with the following, and Plugins on your local development environment: - [Contact Form 7](https://wordpress.org/plugins/contact-form-7/) (Free) -- [Gravity Forms](https://www.gravityforms.com/) (Paid) -- [WishList Member](https://wishlistmember.com/) (Paid) +- [Elementor](https://wordpress.org/plugins/elementor/) (Free) +- [Forminator](https://wordpress.org/plugins/forminator/) (Free) - [WooCommerce](https://wordpress.org/plugins/woocommerce/) (Free) +- [Divi](https://www.elegantthemes.com/gallery/divi/) (Paid) +- [WishList Member](https://wishlistmember.com/) (Paid) For Kit employees or contractors, licensed versions of paid Third Party Plugins can be made available to you on request. @@ -193,7 +195,7 @@ In the Plugin's directory, run the following command to run PHPStan, which will standards, that PHP DocBlocks are valid, WordPress action/filter DocBlocks are valid etc: ```bash -vendor/bin/phpstan --memory-limit=1G +vendor/bin/phpstan analyse --memory-limit=1250M ``` ![PHPStan Test Results](/.github/docs/phpstan.png?raw=true) @@ -222,7 +224,7 @@ If you're new to this, use [GitHub Desktop](https://desktop.github.com/) or [Tow ### Install and Run Dev Containers -- Open Visual Studio Code, and install the [Dev Containers]() extension +- Open Visual Studio Code, and install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension - Open the Visual Studio Code Command Palette (`Ctrl + Shift + P`) - Type `>Dev Container: Rebuild and Reopen in Container`, pressing Enter @@ -264,7 +266,7 @@ In Visual Studio Code's Terminal, navigate to `/workspaces/convertkit-wordpress` standards, that PHP DocBlocks are valid, WordPress action/filter DocBlocks are valid etc: ```bash -vendor/bin/phpstan --configuration phpstan-dev.neon --memory-limit=1G +vendor/bin/phpstan analyse --configuration phpstan-dev.neon --memory-limit=1250M ``` If no Terminal instance is open, you can create a new one by clicking the `+` icon. diff --git a/TESTING.md b/TESTING.md index 131ecb5be..d98d58e4a 100644 --- a/TESTING.md +++ b/TESTING.md @@ -35,7 +35,7 @@ The following Composer commands can be used: | `composer build-js` | `composer build-js` | Builds the frontend JS file | | `composer watch-js` | `composer watch-js` | Builds the frontend JS file when changes are made to frontend JS files | | `composer build` | `composer build` | Fixes, lints and builds frontend CSS and JS | -| `composer static-analysis` | `composer phpstan` | Runs PHPStan static analysis with increased memory limit | +| `composer php-static-analysis` | `composer phpstan` | Runs PHPStan static analysis with increased memory limit | | `composer test` | `composer test` | Builds and runs end-to-end tests with `fail-fast` enabled | | `composer test-integration` | `composer test-integration` | Builds and runs integration tests with `fail-fast` enabled | @@ -260,7 +260,7 @@ For a full list of available wp-browser and Codeception functions that can be us ## Required Test Format -Tests can be run in isolation, as part of a suite of tests, sequentially and/or in parralel across different environments. +Tests can be run in isolation, as part of a suite of tests, sequentially and/or in parallel across different environments. It's therefore required that every Cest contain both `_before()` and `_passed()` functions, which handle: - `_before()`: Performing prerequisite steps (such as Plugin activation, third party Plugin activation and setup) prior to each test, - `_passed()`: Performing cleanup steps (such as Plugin deactivation, removal of Plugin data from the database) after each passing test. @@ -268,6 +268,12 @@ It's therefore required that every Cest contain both `_before()` and `_passed()` The following test format should be used: ```php +activateConvertKitPlugin($I); + $I->activateKitPlugin($I); $I->activateThirdPartyPlugin($I, 'third-party-plugin-slug'); - $I->setupConvertKitPlugin($I); - $I->enableDebugLog($I); + $I->setupKitPlugin($I); } public function testSpecificSteps(EndToEndTester $I) @@ -308,9 +313,9 @@ class ExampleCest */ public function _passed(EndToEndTester $I) { - $I->deactivateConvertKitPlugin($I); + $I->deactivateKitPlugin($I); $I->deactivateThirdPartyPlugin($I, 'third-party-plugin-slug'); - $I->resetConvertKitPlugin($I); + $I->resetKitPlugin($I); } } ``` @@ -321,27 +326,25 @@ Helpers extend testing by registering functions that we might want to use across Codeception or PHPUnit. This helps achieve the principle of DRY code (Don't Repeat Yourself). For example, in the `tests/Support/Helper` directory, our `Xdebug.php` helper contains the `checkNoWarningsAndNoticesOnScreen()` function, -which checks that -- the class does not contain the `php-error` class, which WordPress adds if a PHP error is detected -- no Xdebug errors were output -- no PHP Warnings or Notices were output +which checks that no Xdebug errors or notices (`.xdebug-error`, `.xe-notice`) were output. Our End to End Tests can now call `$I->checkNoWarningsAndNoticesOnScreen($I)`, instead of having to write several lines of code to perform each error check for every test. Further End to End Test Helpers that are provided include: -- `activateConvertKitPlugin($I)`: Logs in to WordPress as the `admin` user, and activates the ConvertKit Plugin. -- `deactivateConvertKitPlugin($I)`: Logs in to WordPress as the `admin` user, and deactivates the ConvertKit Plugin. +- `activateKitPlugin($I)`: Logs in to WordPress as the `admin` user, and activates the Kit Plugin. +- `deactivateKitPlugin($I)`: Logs in to WordPress as the `admin` user, and deactivates the Kit Plugin. - `activateThirdPartyPlugin($I, $name)`: Logs in to WordPress as the `admin` user, and activates the given third party Plugin by its slug. - `deactivateThirdPartyPlugin($I, $name)`: Logs in to WordPress as the `admin` user, and deactivates the given third party Plugin by its slug. -- `setupConvertKitPlugin($I)`: Enters the ConvertKit API Key and Secret in the Plugin's Settings screen, saving it. +- `setupKitPlugin($I, $options = false)`: Writes the Plugin's settings (OAuth Access and Refresh Tokens from `.env.testing`, plus default Forms and other options) directly to the options table. Debug logging is enabled by default, so there's no need to enable it separately. Pass an array of `$options` to override any individual setting. +- `resetKitPlugin($I)`: Removes the Plugin's settings and data from the database, so the next test starts from a known state. Other helpers most likely exist; refer to the [Helper](https://github.com/ConvertKit/convertkit-wordpress/blob/main/tests/Support/Helper/) folder for all available functions. ## Writing Helpers With this methodology, if two or more of your tests perform the same checks, you should: -- add a function to the applicable file in the `tests/Support/Helper` directory (e.g. `tests/Support/Helper/Plugin.php`), +- add a function to the applicable file in the `tests/Support/Helper` directory (e.g. `tests/Support/Helper/KitPlugin.php`), usually in the format of ```php /** @@ -363,7 +366,7 @@ If the function doesn't fit into any existing helper file: - edit the [EndToEnd.suite.yml](https://github.com/ConvertKit/convertkit-wordpress/blob/main/tests/EndToEnd.suite.yml) file, adding the Helper's namespace and class under the `enabled` section. -Need to change how Codeception runs? Edit the [codeception.dist.xml](codeception.dist.xml) file. +Need to change how Codeception runs? Edit the [codeception.dist.yml](codeception.dist.yml) file. ## Block Testing @@ -406,10 +409,14 @@ This will create a PHP test file in the `tests/Integration` directory called `AP ```php ` Helper functions available to End to End tests are not available here — refer to an existing test in +`tests/Integration` for the expected pattern. ## Run Tests @@ -478,7 +487,7 @@ Any errors should be corrected by making applicable code or test changes. ## Run PHP CodeSniffer > **Quick Command** -> `composer coding-standards`: Run PHP Coding Standards on Plugin files +> `composer php-coding-standards` (or `composer phpcs`): Run PHP Coding Standards on Plugin files [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) checks that all Plugin code meets the [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/). @@ -490,9 +499,7 @@ as defined in the `phpcs.xml` configuration: vendor/bin/phpcs ./ --standard=phpcs.xml -v -s ``` -`--standard=phpcs.tests.xml` tells PHP CodeSniffer to use the Coding Standards rules / configuration defined in `phpcs.tests.xml`. -These differ slightly from WordPress' Coding Standards, to ensure that writing tests isn't a laborious task, whilst maintaing consistency -in test coding style. +`--standard=phpcs.xml` tells PHP CodeSniffer to use the Coding Standards rules / configuration defined in `phpcs.xml`. `-v` produces verbose output `-s` specifies the precise rule that failed ![Coding Standards Screenshot](/.github/docs/coding-standards-error.png?raw=true) @@ -510,7 +517,7 @@ Need to change the PHP or WordPress coding standard rules applied? Either: ## Run CSS Linting > **Quick Command** -> `composer lint-css`: Run CSS Coding Standards on Plugin files +> `composer css-coding-standards` (or `composer lint-css`): Run CSS Coding Standards on Plugin files In the Plugin's directory, run the following command to run CSS and WordPress Coding Standards on CSS, which will check the code meets WordPress' Coding Standards as defined in the `.stylelintrc.json` configuration: @@ -532,7 +539,7 @@ Need to change the CSS or WordPress coding standard rules applied? WordPress' C ## Run JS Linting > **Quick Command** -> `composer lint-js`: Run JS Coding Standards on Plugin files +> `composer js-coding-standards` (or `composer lint-js`): Run JS Coding Standards on Plugin files In the Plugin's directory, run the following command to run JS and WordPress Coding Standards on JavaScript, which will check the code meets WordPress' Coding Standards as defined in the `.eslintrc.js` configuration: @@ -550,12 +557,10 @@ Need to change the JS or WordPress coding standard rules applied? WordPress' JS **Rules should be ignored with caution**. -**Rules should be ignored with caution**. - ## Run PHPStan > **Quick Command** -> `composer static-analysis`: Run PHPStan static analysis on Plugin files +> `composer php-static-analysis` (or `composer phpstan`): Run PHPStan static analysis on Plugin files [PHPStan](https://phpstan.org) performs static analysis on the Plugin's PHP code. This ensures: @@ -569,7 +574,7 @@ Need to change the JS or WordPress coding standard rules applied? WordPress' JS In the Plugin's directory, run the following command to run PHPStan: ```bash -vendor/bin/phpstan --memory-limit=1G +vendor/bin/phpstan analyse --memory-limit=1250M ``` Any errors should be corrected by making applicable code changes. @@ -579,7 +584,7 @@ False positives [can be excluded by configuring](https://phpstan.org/user-guide/ ## Run PHP CodeSniffer for Tests > **Quick Command** -> `composer coding-standards-tests`: Run PHP Coding Standards on test files +> `composer php-coding-standards-on-tests` (or `composer phpcs-tests`): Run PHP Coding Standards on test files In the Plugin's directory, run the following command to run PHP_CodeSniffer, which will check the code meets Coding Standards as defined in the `phpcs.tests.xml` configuration: @@ -589,7 +594,7 @@ vendor/bin/phpcs ./tests --standard=phpcs.tests.xml -v -s ``` `--standard=phpcs.tests.xml` tells PHP CodeSniffer to use the Coding Standards rules / configuration defined in `phpcs.tests.xml`. -These differ slightly from WordPress' Coding Standards, to ensure that writing tests isn't a laborious task, whilst maintaing consistency +These differ slightly from WordPress' Coding Standards, to ensure that writing tests isn't a laborious task, whilst maintaining consistency in test coding style. `-v` produces verbose output `-s` specifies the precise rule that failed diff --git a/phpcs.tests.xml b/phpcs.tests.xml index 881d54b65..bb2751c2f 100644 --- a/phpcs.tests.xml +++ b/phpcs.tests.xml @@ -18,7 +18,7 @@ - +