diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index bf6e14d..e7901cf 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -10,7 +10,7 @@ An *approved* Pull Request is when a PR passes all tests **and** has been approv ## Create a New Release -[Create a New Release](https://github.com/ConvertKit/convertkit-wordpress-libraries/releases/new), completing the following: +[Create a New Release](https://github.com/Kit/convertkit-wordpress-libraries/releases/new), completing the following: - Choose a tag: Click this button and enter the new version number (e.g. `1.0.1`) - Release title: The version number (e.g. `1.0.1`) @@ -25,9 +25,9 @@ An *approved* Pull Request is when a PR passes all tests **and** has been approv When you're happy with the above, click `Publish Release`. -## Use the Published Release in ConvertKit Plugins +## Use the Published Release in Kit Plugins -To use the published release in ConvertKit Plugins, **in the ConvertKit Plugin** edit the `composer.json` file to use the tagged version: +To use the published release in Kit Plugins, **in the Kit Plugin** edit the `composer.json` file to use the tagged version: ``` "require": { @@ -35,4 +35,4 @@ To use the published release in ConvertKit Plugins, **in the ConvertKit Plugin** }, ``` -The specific version number tells Composer that we want to use a specific tag of this repository in our ConvertKit Plugin. [Read more](https://getcomposer.org/doc/articles/versions.md#vcs-tags-and-branches). \ No newline at end of file +The specific version number tells Composer that we want to use a specific tag of this repository in our Kit Plugin. [Read more](https://getcomposer.org/doc/articles/versions.md#vcs-tags-and-branches). \ No newline at end of file diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md deleted file mode 100644 index b6182f2..0000000 --- a/DEVELOPMENT.md +++ /dev/null @@ -1,67 +0,0 @@ -# Development Guide - -This document describes the high level workflow used when working on the ConvertKit WordPress Libraries. - -You're free to use your preferred IDE and Git client. - -## Prerequisites - -If you haven't yet set up your local development environment with the ConvertKit WordPress Libraries repository installed, refer to the [Setup Guide](SETUP.md). - -## Create a Branch - -In your Git client / command line, create a new branch: -- If this is for a new feature that does not have a GitHub Issue number, enter a short descriptive name for the branch, relative to what you're working on -- If this is for a feature/bug that has a GitHub Issue number, enter issue-XXX, replacing XXX with the GitHub issue number - -Once done, make sure you've switched to your new branch, and begin making the necessary code additions/changes/deletions. - -## Using this Branch in a ConvertKit Plugin - -To reflect the changes you're making to this library in a ConvertKit Plugin, edit the `composer.json` file in that Plugin (not this repository), -changing `{branch_name}` to the branch name you created in the `Create a Branch` step above. -``` -"require": { - "convertkit/convertkit-wordpress-libraries": "dev-{branch_name}" -}, -``` - -For example, if our branch name is `products-api`, the `composer.json` file in the ConvertKit Plugin (not this repository) would read: -``` -"require": { - "convertkit/convertkit-wordpress-libraries": "dev-products-api" -}, -``` - -The `dev-` prefix tells Composer that we want to use a specific branch of this repository in our ConvertKit Plugin. [Read more](https://getcomposer.org/doc/articles/versions.md#vcs-tags-and-branches). - -## Coding Standards - -Code must follow [WordPress Coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/), which is checked -when running tests (more on this below). - -## Security and Sanitization - -When [outputting data](https://developer.wordpress.org/plugins/security/securing-output/), escape it using WordPress' escaping functions such as `esc_html()`, `esc_attr__()`, `wp_kses()`, `wp_kses_post()`. - -When reading [user input](https://developer.wordpress.org/plugins/security/securing-input/), sanitize it using WordPress' sanitization functions such as `sanitize_text_field()`, `sanitize_textarea_field()`. - -When writing to the database, prepare database queries using ``$wpdb->prepare()`` - -Never trust user input. Sanitize it. - -Make use of [WordPress nonces](https://codex.wordpress.org/WordPress_Nonces) for saving form submitted data. - -Coding standards will catch any sanitization, escaping or database queries that aren't prepared. - -## Committing Work - -Remember to commit your changes to your branch relatively frequently, with a meaningful, short summary that explains what the change(s) do. -This helps anyone looking at the commit history in the future to find what they might be looking for. - -If it's a particularly large commit, be sure to include more information in the commit's description. - -## Next Steps - -Once you've finished your feature or issue, you must write/amend tests for it. Refer to the [Testing Guide](TESTING.md) for a detailed walkthrough -on how to write a test. \ No newline at end of file diff --git a/README.md b/README.md index 6ada8e8..11018ea 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,20 @@ -# ConvertKit WordPress Libraries +# Kit WordPress Libraries -Welcome to the ConvertKit WordPress Libraries repository on GitHub. Here you can view the source code, review open issues, and see releases of our WordPress specific libraries. +Welcome to the Kit WordPress Libraries repository on GitHub. Here you can view the source code, review open issues, and see releases of our WordPress specific libraries. -If you're not a developer, please download a ConvertKit plugin from wordpress.org: -- [ConvertKit](https://wordpress.org/plugins/convertkit/) -- [ConvertKit for Gravity Forms](https://wordpress.org/plugins/convertkit-gravity-forms/) -- [ConvertKit for WooCommerce](https://wordpress.org/plugins/convertkit-woocommerce/) +If you're not a developer, please download a Kit plugin from wordpress.org: +- [Kit](https://wordpress.org/plugins/convertkit/) +- [Kit for WooCommerce](https://wordpress.org/plugins/convertkit-woocommerce/) +- [Kit for WPForms](https://wordpress.org/plugins/integrate-convertkit-wpforms/) +- [Kit for MemberMouse](https://wordpress.org/plugins/convertkit-membermouse/) ## Developers -For ConvertKit Developers, there are guides covering: -- [Setup](SETUP.md) - setting up your local environment for development and testing -- [Development](DEVELOPMENT.md) - best practices for development -- [Testing](TESTING.md) - how to write and run tests +For Kit Developers, there are guides in the main Kit Plugin repository covering: +- [Setup](https://github.com/Kit/convertkit-wordpress/blob/main/SETUP.md) - setting up your local environment for development and testing +- [Development](https://github.com/Kit/convertkit-wordpress/blob/main/DEVELOPMENT.md) - best practices for development +- [Testing](https://github.com/Kit/convertkit-wordpress/blob/main/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 + +For Kit, there is a separate guide to deploying new versions: - [Deployment](DEPLOYMENT.md) - how to publish versioned updates to this library \ No newline at end of file diff --git a/SETUP.md b/SETUP.md deleted file mode 100644 index effc5ec..0000000 --- a/SETUP.md +++ /dev/null @@ -1,120 +0,0 @@ -# Setup Guide - -This document describes how to setup your development environment, so that it is ready to develop and test the ConvertKit WordPress Libraries. - -Suggestions are provided for the LAMP/LEMP stack and Git client are for those who prefer the UI over a command line and/or are less familiar with -WordPress, PHP, MySQL and Git - but you're free to use your preferred software. - -## Setup - -### LAMP/LEMP stack - -Any Apache/nginx, PHP 7.x+ and MySQL 5.8+ stack running WordPress. For example, but not limited to: -- Local by Flywheel (recommended) -- Docker -- MAMP -- WAMP -- VVV - -### Composer - -If [Composer](https://getcomposer.org) is not installed on your local environment, enter the following commands at the command line to install it: - -```bash -php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" -php -r "if (hash_file('sha384', 'composer-setup.php') === '906a84df04cea2aa72f40b5f787e49f22d4c2f19492ac310e8cba5b96ac8b64115ac402c8cd292b8a03482574915d1a8') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;" -php composer-setup.php -php -r "unlink('composer-setup.php');" -sudo mv composer.phar /usr/local/bin/composer -``` - -Confirm that installation was successful by entering the `composer` command at the command line - -### Clone Repository - -Using your preferred Git client or command line, clone this repository into the `wp-content/plugins/` folder of your local WordPress installation. - -If you prefer to clone the repository elsewhere, and them symlink it to your local WordPress installation, that will work as well. - -If you're new to this, use [GitHub Desktop](https://desktop.github.com/) or [Tower](https://www.git-tower.com/mac) - -### Create Test Database - -Create a blank `test` database in MySQL, with a MySQL user who can read and write to it. - -### Configure Testing Environment - -Copy the `.env.example` file to `.env.testing` in the root of this repository, changing folder and database credentials as necessary. - -#### Codeception - -Create a `codeception.yml` file in the root of the repository, with the following contents: -```yaml -params: - - .env.testing -``` - -This tells Codeception to read the above `.env.testing` file when testing on the local development enviornment. - -#### PHPStan - -Copy the `phpstan.neon.example` file to `phpstan.neon` in the root of this repository, changing the `scanDirectories` to point to your -local WordPress installation. - -### Install Packages - -In the Plugin's directory, at the command line, run `composer install`. - -This will install packages used in the process of development (i.e. testing, coding standards): -- wp-browser -- Codeception -- PHPStan -- PHPUnit -- PHP_CodeSniffer - -How to use these is covered later on, and in the [Testing Guide](TESTING.md) - -### Running the Test Suite - -In a Terminal window, build and run the tests to make sure there are no errors and that you have correctly setup your environment: - -```bash -vendor/bin/codecept build -vendor/bin/codecept run wpunit -``` - -![Codeception Test Results](/.github/docs/codeception.png?raw=true) - -Don't worry if you don't understand these commands; if your output looks similar to the above screenshot, and no test is prefixed with `E`, -your environment is setup successfully. - -### Running CodeSniffer - -In the Plugin's directory, run the following command to run PHP_CodeSniffer, which will check the code meets WordPress' Coding Standards: - -```bash -vendor/bin/phpcs ./ -v -s -``` - -![Coding Standards Test Results](/.github/docs/coding-standards.png?raw=true) - -Again, don't worry if you don't understand these commands; if your output looks similar to the above screenshot, with no errors, your environment -is setup successfully. - -### Running PHPStan - -In the Plugin's directory, run the following command to run PHPStan, which will perform static analysis on the code, checking it meets required -standards, that PHP DocBlocks are valid, WordPress action/filter DocBlocks are valid etc: - -```bash -vendor/bin/phpstan --memory-limit=1G -``` - -![PHPStan Test Results](/.github/docs/phpstan.png?raw=true) - -Again, don't worry if you don't understand these commands; if your output looks similar to the above screenshot, with no errors, your environment -is setup successfully. - -### Next Steps - -With your development environment setup, you'll probably want to start development, which is covered in the [Development Guide](DEVELOPMENT.md) \ No newline at end of file diff --git a/TESTING.md b/TESTING.md deleted file mode 100644 index d456241..0000000 --- a/TESTING.md +++ /dev/null @@ -1,148 +0,0 @@ -# Testing Guide - -This document describes how to: -- create and run tests for your development work, -- ensure code meets PHP and WordPress Coding Standards, for best practices and security, -- ensure code passes static analysis, to catch potential errors that tests might miss - -If you're new to creating and running tests, this guide will walk you through how to do this. - -For those more experienced with creating and running tests, our tests are written in PHP using [wp-browser](https://wpbrowser.wptestkit.dev/) -and [Codeception](https://codeception.com/docs/01-Introduction). - -## Prerequisites - -If you haven't yet set up your local development environment with the ConvertKit WordPress Library repository installed, refer to the [Setup Guide](SETUP.md). - -If you haven't yet created a branch and made any code changes to the Library, refer to the [Development Guide](DEVELOPMENT.md) - -## Write (or modify) a test - -If you're new to testing, or testing within WordPress, there's a detailed Codeception guide in the [main ConvertKit Plugin]https://github.com/ConvertKit/convertkit-wordpress/blob/main/TESTING.md#types-of-test - -For the WordPress Libraries, you'll most likely only need a WordPress Unit Test. - -## Writing a WordPress Unit Test - -WordPress Unit tests provide testing of Plugin specific functions and/or classes, typically to assert that they perform as expected -by a developer. This is primarily useful for testing our API class, and confirming that any Plugin registered filters return -the correct data. - -To create a new WordPress Unit Test, at the command line in the Plugin's folder, enter the following command, replacing `APITest` -with a meaningful name of what the test will perform: - -```bash -php vendor/bin/codecept generate:wpunit wpunit APITest -``` - -This will create a PHP test file in the `tests/wpunit` directory called `APITest.php` - -```php -post->create_and_get(); - - $this->assertInstanceOf(\WP_Post::class, $post); - } -} -``` - -Helpers can be used for WordPress Unit Tests, similar to how they can be used for acceptance tests. -To register your own helper function, add it to the `tests/_support/Helper/Wpunit.php` file. - -## Run Tests - -Once you have written your code and test(s), run the tests to make sure there are no errors. - -To run the tests, enter the following commands in a Terminal window: - -```bash -vendor/bin/codecept build -vendor/bin/codecept run wpunit -``` - -If a test fails, you can inspect the output in the Terminal. - -Any errors should be corrected by making applicable code or test changes. - -## Run PHP CodeSniffer - -[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/). - -In the Plugin's directory, run the following command to run PHP_CodeSniffer, which will check the code meets WordPress' Coding Standards: - -```bash -vendor/bin/phpcs ./ -v -s -``` - -`-v` produces verbose output, and `-s` specifies the precise rule that failed: -![Coding Standards Screenshot](/.github/docs/coding-standards-error.png?raw=true) - -Any errors should be corrected by either: -- making applicable code changes -- (Experimental) running `vendor/bin/phpcbf ./ -v` to automatically fix coding standards - -Need to change the PHP or WordPress coding standard rules applied? Either: -- ignore a rule in the affected code, by adding `phpcs:ignore {rule}`, where {rule} is the given rule that failed in the above output. -- edit the [phpcs.xml](phpcs.xml) file. - -**Rules should be ignored with caution**, particularly when sanitizing and escaping data. - -## Run PHPStan - -[PHPStan](https://phpstan.org) performs static analysis on the Plugin's PHP code. This ensures: - -- DocBlocks declarations are valid and uniform -- DocBlocks declarations for WordPress `do_action()` and `apply_filters()` calls are valid -- Typehinting variables and return types declared in DocBlocks are correctly cast -- Any unused functions are detected -- Unnecessary checks / code is highlighted for possible removal -- Conditions that do not evaluate can be fixed/removed as necessary - -In the Plugin's directory, run the following command to run PHPStan: - -```bash -vendor/bin/phpstan --memory-limit=1G -``` - -Any errors should be corrected by making applicable code changes. - -False positives [can be excluded by configuring](https://phpstan.org/user-guide/ignoring-errors) the `phpstan.neon` file. - -## Next Steps - -Once your test(s) are written and successfully run locally, submit your branch via a new [Pull Request](https://github.com/ConvertKit/convertkit-wordpress-libraries/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. - -If the PR tests fail, you can make code changes as necessary, pushing to the same branch. This will trigger the tests to run again. - -If the PR tests pass, you can publish the PR, assigning some reviewers. \ No newline at end of file diff --git a/composer.json b/composer.json index 99b02b7..94795b2 100644 --- a/composer.json +++ b/composer.json @@ -18,6 +18,26 @@ "lucatume/wp-browser": "^3.0 || ^4.0" }, "minimum-stability": "stable", + "scripts": { + "phpcs": "vendor/bin/phpcs ./ -s -v", + "phpcbf": "vendor/bin/phpcbf ./ -s -v", + "phpcs-tests": "vendor/bin/phpcs ./tests --standard=phpcs.tests.xml -s -v", + "phpcbf-tests": "vendor/bin/phpcbf ./tests --standard=phpcs.tests.xml -s -v", + "phpstan": "vendor/bin/phpstan analyse --memory-limit=1250M", + "coding-standards": "vendor/bin/phpcs ./ -s -v", + "fix-coding-standards": "vendor/bin/phpcbf ./ -s -v", + "coding-standards-on-tests": "vendor/bin/phpcs ./tests --standard=phpcs.tests.xml -s -v", + "fix-coding-standards-on-tests": "vendor/bin/phpcbf ./tests --standard=phpcs.tests.xml -s -v", + "static-analysis": "vendor/bin/phpstan analyse --memory-limit=1250M", + "test": [ + "vendor/bin/codecept build @no_additional_args", + "vendor/bin/codecept run EndToEnd @additional_args --fail-fast" + ], + "test-integration": [ + "vendor/bin/codecept build @no_additional_args", + "vendor/bin/codecept run Integration @additional_args --fail-fast" + ] + }, "config": { "allow-plugins": { "dealerdirect/phpcodesniffer-composer-installer": true