templates-patterns-collection
Last commit date
assets
2 weeks ago
beaver
1 year ago
e2e-tests
2 weeks ago
editor
1 year ago
elementor
1 year ago
includes
2 weeks ago
languages
2 weeks ago
migration
5 years ago
onboarding
2 weeks ago
shared
2 years ago
vendor
2 weeks ago
.browserslistrc
1 year ago
.eslintrc
1 year ago
AGENTS.md
2 weeks ago
CHANGELOG.md
2 weeks ago
CONTRIBUTING.md
2 years ago
README.md
2 weeks ago
phpstan.neon
2 weeks ago
readme.txt
2 weeks ago
templates-patterns-collection.php
2 weeks ago
yarn.lock
1 year ago
CONTRIBUTING.md
309 lines
| 1 | |
| 2 | ## Releasing |
| 3 | |
| 4 | This repository uses conventional [](https://github.com/Codeinwp/conventional-changelog-simple-presetchangelog commit](https://github.com/Codeinwp/conventional-changelog-simple-preset](https://github.com/Codeinwp/conventional-changelog-simple-preset) messages to trigger release |
| 5 | |
| 6 | How to release a new version: |
| 7 | |
| 8 | - Clone the master branch |
| 9 | - Do your changes |
| 10 | - Send a PR to master and merge it using the following subject message |
| 11 | - `release: <release short description>` - for patch release |
| 12 | - `release(minor): <release short description>` - for minor release |
| 13 | - `release(major): <release short description>` - for major release |
| 14 | The release notes will inherit the body of the commit message which triggered the release. For more details check the [](https://github.com/Codeinwp/conventional-changelog-simple-presetsimple-preset](https://github.com/Codeinwp/conventional-changelog-simple-preset](https://github.com/Codeinwp/conventional-changelog-simple-preset) that we use. |
| 15 | |
| 16 | |
| 17 | # CONTRIBUTING GUIDELINES |
| 18 | + [](#setup-guideSetup Guide](#setup-guide](#setup-guide) |
| 19 | + [](#development-guideDevelopment Guide](#development-guide](#development-guide) |
| 20 | + [](#testing-guideTesting Guide](#testing-guide](#testing-guide) |
| 21 | |
| 22 | # Setup Guide |
| 23 | |
| 24 | This document describes how to set up your development environment, so that it is ready to run, develop and test this WordPress Plugin or Theme. |
| 25 | |
| 26 | 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 |
| 27 | WordPress, PHP, MySQL and Git - but you're free to use your preferred software. |
| 28 | |
| 29 | ## Setup |
| 30 | |
| 31 | ### LAMP/LEMP stack |
| 32 | |
| 33 | Any Apache/nginx, PHP 7.x+ and MySQL 5.8+ stack running WordPress. For example, but not limited to: |
| 34 | - Valet (recommended) |
| 35 | - Local by Flywheel |
| 36 | - Docker |
| 37 | - MAMP |
| 38 | - WAMP |
| 39 | |
| 40 | ### Composer |
| 41 | |
| 42 | If [](https://getcomposer.orgComposer](https://getcomposer.org](https://getcomposer.org) is not installed on your local environment, enter the following commands at the command line to install it: |
| 43 | |
| 44 | ```bash |
| 45 | php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" |
| 46 | php -r "if (hash_file('sha384', 'composer-setup.php') === '906a84df04cea2aa72f40b5f787e49f22d4c2f19492ac310e8cba5b96ac8b64115ac402c8cd292b8a03482574915d1a8') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;" |
| 47 | php composer-setup.php |
| 48 | php -r "unlink('composer-setup.php');" |
| 49 | sudo mv composer.phar /usr/local/bin/composer |
| 50 | ``` |
| 51 | |
| 52 | Confirm that installation was successful by entering the `composer --version` command at the command line |
| 53 | |
| 54 | ### Clone Repository |
| 55 | |
| 56 | Using your preferred Git client or command line, clone this repository into the `wp-content/plugins/` folder of your local WordPress installation. |
| 57 | |
| 58 | If you prefer to clone the repository elsewhere, and them symlink it to your local WordPress installation, that will work as well. |
| 59 | |
| 60 | If you're new to this, use [](https://desktop.github.com/GitHub Desktop](https://desktop.github.com/](https://desktop.github.com/) or [](https://www.git-tower.com/macTower](https://www.git-tower.com/mac](https://www.git-tower.com/mac) |
| 61 | |
| 62 | For Plugins the cloned folder should be under `wp-content/plugins/` and for Themes under `wp-content/themes/`. |
| 63 | |
| 64 | ### Install Dependencies for PHP and JS |
| 65 | |
| 66 | In the cloned repository's directory, at the command line, run `composer install`. |
| 67 | This will install the development dependencies. If you want to install just the production dependencies, run `composer install --no-dev`. |
| 68 | |
| 69 | The development dependencies include: |
| 70 | - PHPStan |
| 71 | - PHPUnit |
| 72 | - PHP_CodeSniffer |
| 73 | - WordPress Coding Standards |
| 74 | - WordPress PHPUnit Polyfills |
| 75 | |
| 76 | For the JS dependencies, run `npm install`. |
| 77 | To watch for changes in the JS files, run `npm run dev` if present or `npm run dist` to build a new version. |
| 78 | |
| 79 | ### PHP_CodeSniffer |
| 80 | |
| 81 | To run PHP_CodeSniffer, run `composer lint`. This will run the WordPress Coding Standards checks. |
| 82 | To fix automatically fixable issues, run `composer format`. |
| 83 | |
| 84 | ### PHPUnit |
| 85 | |
| 86 | To run PHPUnit, run `phpunit` or `./vendor/bin/phpunit` if it is not configured globally. |
| 87 | |
| 88 | ### E2E Tests |
| 89 | If the folder `e2e-tests` is present, you can run the E2E tests by following the instructions in the [](./e2e-tests/README.mdE2E testing](./e2e-tests/README.md](./e2e-tests/README.md). |
| 90 | |
| 91 | ### Next Steps |
| 92 | |
| 93 | With your development environment setup, you'll probably want to start development, which is covered bellow in the **Development Guide**. |
| 94 | |
| 95 | |
| 96 | |
| 97 | # Development Guide |
| 98 | |
| 99 | This document describes the high level workflow used when working on a WordPress Plugin or Theme. |
| 100 | |
| 101 | You're free to use your preferred IDE and Git client. We recommend PHPStorm or Visual Studio Code, and GitHub CLI. |
| 102 | |
| 103 | ## Prerequisites |
| 104 | |
| 105 | If you haven't yet set up your local development environment with a WordPress Plugin repository installed, refer to the [](#setup-guideSetup Guide](#setup-guide](#setup-guide). |
| 106 | |
| 107 | his 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 |
| 108 | - If this is for a feature/bug that has a GitHub Issue number, enter feat/issue_name or fix/issue_name, where issue_name is a descriptive name for the issue |
| 109 | |
| 110 | Once done, make sure you've switched to your new branch, and begin making the necessary code additions/changes/deletions. |
| 111 | |
| 112 | ## Coding Standards |
| 113 | |
| 114 | Code must follow [](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/WordPress Coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/), which is checked |
| 115 | when running tests (more on this below). |
| 116 | |
| 117 | ## Security and Sanitization |
| 118 | |
| 119 | When [](https://developer.wordpress.org/plugins/security/securing-output/outputting data](https://developer.wordpress.org/plugins/security/securing-output/](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()`. |
| 120 | |
| 121 | When reading [](https://developer.wordpress.org/plugins/security/securing-input/user input](https://developer.wordpress.org/plugins/security/securing-input/](https://developer.wordpress.org/plugins/security/securing-input/), sanitize it using WordPress' sanitization functions such as `sanitize_text_field()`, `sanitize_textarea_field()`. |
| 122 | |
| 123 | When writing to the database, prepare database queries using ``$wpdb->prepare()`` |
| 124 | |
| 125 | Never trust user input. Sanitize it. |
| 126 | |
| 127 | Make use of [](https://codex.wordpress.org/WordPress_NoncesWordPress nonces](https://codex.wordpress.org/WordPress_Nonces](https://codex.wordpress.org/WordPress_Nonces) for saving form submitted data. |
| 128 | |
| 129 | Coding standards will catch any sanitization, escaping or database queries that aren't prepared. |
| 130 | |
| 131 | ## Composer Packages |
| 132 | |
| 133 | We use Composer for package management. A package can be added to one of two sections of the `composer.json` file: `require` or `require-dev`. |
| 134 | |
| 135 | ### "require" |
| 136 | |
| 137 | Packages listed in the "require" directive are packages that the Plugin needs in order to function for end users. |
| 138 | |
| 139 | These packages are included when the Plugin is deployed to WordPress.org |
| 140 | |
| 141 | Typically, packages listed in this section would be libraries that the Plugin uses. |
| 142 | |
| 143 | ### "require-dev" |
| 144 | |
| 145 | Packages listed in the "require-dev" directive are packages that the Plugin **does not** need in order to function for end users. |
| 146 | |
| 147 | These packages are **not** included when the Plugin is deployed to wordpress.org |
| 148 | |
| 149 | Typically, packages listed in this section would be internal development tools for testing, such as: |
| 150 | - Coding Standards |
| 151 | - PHPStan |
| 152 | - PHPUnit |
| 153 | |
| 154 | ## Committing Work |
| 155 | |
| 156 | Remember to commit your changes to your branch relatively frequently, with a meaningful, short summary that explains what the change(s) do. |
| 157 | This helps anyone looking at the commit history in the future to find what they might be looking for. |
| 158 | |
| 159 | If it's a particularly large commit, be sure to include more information in the commit description. |
| 160 | |
| 161 | ## Next Steps |
| 162 | |
| 163 | Once you've finished your feature or issue, you must write/amend tests for it. Refer to the [](#testing-guideTesting Guide](#testing-guide](#testing-guide) for a detailed walkthrough |
| 164 | on how to write a test. |
| 165 | |
| 166 | |
| 167 | |
| 168 | # Testing Guide |
| 169 | |
| 170 | This document describes how to: |
| 171 | - create and run tests for your development work, |
| 172 | - ensure code meets PHP and WordPress Coding Standards, for best practices and security, |
| 173 | - ensure code passes static analysis, to catch potential errors that tests might miss |
| 174 | |
| 175 | If you're new to creating and running tests, this guide will walk you through how to do this. |
| 176 | |
| 177 | For those more experienced with creating and running tests, our tests are written in TS for [](https://playwright.dev/Playwright](https://playwright.dev/](https://playwright.dev/) used for End-to-End testing, |
| 178 | and in PHP for [](https://phpunit.de/PHPUnit](https://phpunit.de/](https://phpunit.de/). |
| 179 | |
| 180 | A PHPUnit guide for WordPress can be found [](https://make.wordpress.org/core/handbook/testing/automated-testing/phpunit/here](https://make.wordpress.org/core/handbook/testing/automated-testing/phpunit/](https://make.wordpress.org/core/handbook/testing/automated-testing/phpunit/). |
| 181 | |
| 182 | ## Prerequisites |
| 183 | |
| 184 | If you haven't yet set up your local development environment with this Plugin repository installed, refer to the [](#setup-guideSetup Guide](#setup-guide](#setup-guide). |
| 185 | |
| 186 | If you haven't yet created a branch and made any code changes to the Plugin or Theme, refer to the [](#development-guideDevelopment Guide](#development-guide](#development-guide) |
| 187 | |
| 188 | ## Write (or modify) a test |
| 189 | |
| 190 | If your work creates new functionality, write a test. |
| 191 | |
| 192 | If your work fixes existing functionality, check if a test exists. Either update that test, or create a new test if one doesn't exist. |
| 193 | |
| 194 | Tests are written in TS using [](https://playwright.dev/Playwright](https://playwright.dev/](https://playwright.dev/) and PHP using [](https://phpunit.de/PHPUnit](https://phpunit.de/](https://phpunit.de/). |
| 195 | |
| 196 | ## Types of Test |
| 197 | |
| 198 | There are different types of tests that can be written: |
| 199 | - Acceptance Tests: Test as a non-technical user in the web browser. |
| 200 | - Functional Tests: Test the framework (WordPress). |
| 201 | - Integration Tests: Test code modules in the context of a WordPress website. |
| 202 | - Unit Tests: Test single PHP classes or functions in isolation. |
| 203 | - WordPress Unit Tests: Test single PHP classes or functions in isolation, with WordPress functions and classes loaded. |
| 204 | |
| 205 | There is no definitive / hard guide, as a test can typically overlap into different types (such as Acceptance and Functional). |
| 206 | |
| 207 | The most important thing is that you have a test for *something*. If in doubt, an Acceptance Test will suffice. |
| 208 | |
| 209 | ### Writing an Acceptance Test |
| 210 | |
| 211 | An acceptance test is a test that simulates a user interacting with the Plugin or Theme in a web browser. |
| 212 | Refer to Writing an End-to-End Test below. |
| 213 | |
| 214 | ### Writing an End-to-End Test |
| 215 | |
| 216 | To write an End-to-End test, create a new file under `e2e-tests/specs` with the name of the spec or functionality you are testing, and add `.spec.test` to the file name. |
| 217 | |
| 218 | E.g. for `e2e-tests/specs/checkout.spec.test.js`, the test file should be `checkout.spec.test.js`. |
| 219 | |
| 220 | For more information on writing End-to-End tests, refer to the [](https://playwright.dev/docs/test-introPlaywright documentation](https://playwright.dev/docs/test-intro](https://playwright.dev/docs/test-intro). |
| 221 | |
| 222 | You can check End-to-End [](./e2e-tests/README.mdREADME](./e2e-tests/README.md](./e2e-tests/README.md) for more details. |
| 223 | |
| 224 | ## Writing a WordPress Unit Test |
| 225 | |
| 226 | WordPress Unit tests provide testing of Plugin/Theme specific functions and/or classes, typically to assert that they perform as expected |
| 227 | by a developer. This is primarily useful for testing our API class, and confirming that any Plugin registered filters return |
| 228 | the correct data. |
| 229 | |
| 230 | To create a new WordPress Unit Test, create a new file under `tests/php/unit` with the name of the class you are testing, and the suffix `Test`. |
| 231 | The filename should be in `lower-case-with-dash`, and the class name should be in `CamelCase`. |
| 232 | |
| 233 | E.g. for `tests/php/unit/class-api-test.php`, the test class should be `class APITest extends \PHPUnit\Framework\TestCase`. |
| 234 | |
| 235 | ```php |
| 236 | <?php |
| 237 | class APITest extends \PHPUnit\Framework\TestCase |
| 238 | { |
| 239 | /** |
| 240 | * @var \WpunitTester |
| 241 | */ |
| 242 | protected $tester; |
| 243 | |
| 244 | public function setUp(): void |
| 245 | { |
| 246 | // Before... |
| 247 | parent::setUp(); |
| 248 | // Your set up methods here. |
| 249 | } |
| 250 | public function tearDown(): void |
| 251 | { |
| 252 | // Your tear down methods here. |
| 253 | // Then... |
| 254 | parent::tearDown(); |
| 255 | } |
| 256 | // Tests |
| 257 | public function test_it_works() |
| 258 | { |
| 259 | $post = static::factory()->post->create_and_get(); |
| 260 | |
| 261 | $this->assertInstanceOf(\WP_Post::class, $post); |
| 262 | } |
| 263 | } |
| 264 | ``` |
| 265 | |
| 266 | ## Run PHPUnit Tests |
| 267 | |
| 268 | Once you have written your code and test(s), run the tests to make sure there are no errors. |
| 269 | |
| 270 | ```bash |
| 271 | ./vendor/bin/phpunit tests/php/unit/class-api-test.php |
| 272 | ``` |
| 273 | |
| 274 | Any errors should be corrected by making applicable code or test changes. |
| 275 | |
| 276 | ## Run PHP CodeSniffer |
| 277 | |
| 278 | In the Plugin's or Theme's directory, run the following command to run PHP_CodeSniffer, which will check the code meets Coding Standards |
| 279 | as defined in the `phpcs.tests.xml` configuration: |
| 280 | |
| 281 | ```bash |
| 282 | composer run lint |
| 283 | ``` |
| 284 | |
| 285 | `--standard=phpcs.tests.xml` tells PHP CodeSniffer to use the Coding Standards rules / configuration defined in `phpcs.tests.xml`. |
| 286 | These differ slightly from WordPress' Coding Standards, to ensure that writing tests isn't a laborious task, whilst maintain consistency |
| 287 | in test coding style. |
| 288 | `-v` produces verbose output |
| 289 | `-s` specifies the precise rule that failed |
| 290 | |
| 291 | Any errors should be corrected by either: |
| 292 | - making applicable code changes |
| 293 | - running `composer run format` to automatically fix coding standards |
| 294 | |
| 295 | Need to change the PHP or WordPress coding standard rules applied? Either: |
| 296 | - ignore a rule in the affected code, by adding `phpcs:ignore {rule}`, where {rule} is the given rule that failed in the above output. |
| 297 | - edit the [](phpcs.tests.xmlphpcs.tests.xml](phpcs.tests.xml](phpcs.tests.xml) file. |
| 298 | |
| 299 | ## Next Steps |
| 300 | |
| 301 | Once your test(s) are written and successfully run locally, submit your branch via a new **Pull Request**. |
| 302 | |
| 303 | 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 |
| 304 | double-check all tests pass. |
| 305 | |
| 306 | 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. |
| 307 | |
| 308 | If the PR tests pass, you can publish the PR, assigning some reviewers. |
| 309 |