You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+294-1Lines changed: 294 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,4 +10,297 @@ How to release a new version:
10
10
-`release: <release short description>` - for patch release
11
11
-`release(minor): <release short description>` - for minor release
12
12
-`release(major): <release short description>` - for major release
13
-
The release notes will inherit the body of the commit message which triggered the release. For more details check the [simple-preset](https://github.com/Codeinwp/conventional-changelog-simple-preset) that we use.
13
+
The release notes will inherit the body of the commit message which triggered the release. For more details check the [simple-preset](https://github.com/Codeinwp/conventional-changelog-simple-preset) that we use.
14
+
15
+
# CONTRIBUTING GUIDELINES
16
+
+[Setup Guide](#setup-guide)
17
+
+[Development Guide](#development-guide)
18
+
+[Testing Guide](#testing-guide)
19
+
20
+
# Setup Guide
21
+
22
+
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.
23
+
24
+
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
25
+
WordPress, PHP, MySQL and Git - but you're free to use your preferred software.
26
+
27
+
## Setup
28
+
29
+
### LAMP/LEMP stack
30
+
31
+
Any Apache/nginx, PHP 7.x+ and MySQL 5.8+ stack running WordPress. For example, but not limited to:
32
+
- Valet (recommended)
33
+
- Local by Flywheel
34
+
- Docker
35
+
- MAMP
36
+
- WAMP
37
+
38
+
### Composer
39
+
40
+
If [Composer](https://getcomposer.org) is not installed on your local environment, enter the following commands at the command line to install it:
Confirm that installation was successful by entering the `composer --version` command at the command line
51
+
52
+
### Clone Repository
53
+
54
+
Using your preferred Git client or command line, clone this repository into the `wp-content/plugins/` folder of your local WordPress installation.
55
+
56
+
If you prefer to clone the repository elsewhere, and them symlink it to your local WordPress installation, that will work as well.
57
+
58
+
If you're new to this, use [GitHub Desktop](https://desktop.github.com/) or [Tower](https://www.git-tower.com/mac)
59
+
60
+
For Plugins the cloned folder should be under `wp-content/plugins/` and for Themes under `wp-content/themes/`.
61
+
62
+
### Install Dependencies for PHP and JS
63
+
64
+
In the cloned repository's directory, at the command line, run `composer install`.
65
+
This will install the development dependencies. If you want to install just the production dependencies, run `composer install --no-dev`.
66
+
67
+
The development dependencies include:
68
+
- PHPStan
69
+
- PHPUnit
70
+
- PHP_CodeSniffer
71
+
- WordPress Coding Standards
72
+
- WordPress PHPUnit Polyfills
73
+
74
+
For the JS dependencies, run `npm install`.
75
+
To watch for changes in the JS files, run `npm run dev` if present or `npm run dist` to build a new version.
76
+
77
+
### PHP_CodeSniffer
78
+
79
+
To run PHP_CodeSniffer, run `composer lint`. This will run the WordPress Coding Standards checks.
80
+
To fix automatically fixable issues, run `composer format`.
81
+
82
+
### PHPUnit
83
+
84
+
To run PHPUnit, run `phpunit` or `./vendor/bin/phpunit` if it is not configured globally.
85
+
86
+
### E2E Tests
87
+
If the folder `e2e-tests` is present, you can run the E2E tests by following the instructions in the [E2E testing](./e2e-tests/README.md).
88
+
89
+
### Next Steps
90
+
91
+
With your development environment setup, you'll probably want to start development, which is covered bellow in the **Development Guide**.
92
+
93
+
94
+
95
+
# Development Guide
96
+
97
+
This document describes the high level workflow used when working on a WordPress Plugin or Theme.
98
+
99
+
You're free to use your preferred IDE and Git client. We recommend PHPStorm or Visual Studio Code, and GitHub CLI.
100
+
101
+
## Prerequisites
102
+
103
+
If you haven't yet set up your local development environment with a WordPress Plugin repository installed, refer to the [Setup Guide](#setup-guide).
104
+
105
+
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
106
+
- 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
107
+
108
+
Once done, make sure you've switched to your new branch, and begin making the necessary code additions/changes/deletions.
109
+
110
+
## Coding Standards
111
+
112
+
Code must follow [WordPress Coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/), which is checked
113
+
when running tests (more on this below).
114
+
115
+
## Security and Sanitization
116
+
117
+
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()`.
118
+
119
+
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()`.
120
+
121
+
When writing to the database, prepare database queries using ``$wpdb->prepare()``
122
+
123
+
Never trust user input. Sanitize it.
124
+
125
+
Make use of [WordPress nonces](https://codex.wordpress.org/WordPress_Nonces) for saving form submitted data.
126
+
127
+
Coding standards will catch any sanitization, escaping or database queries that aren't prepared.
128
+
129
+
## Composer Packages
130
+
131
+
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`.
132
+
133
+
### "require"
134
+
135
+
Packages listed in the "require" directive are packages that the Plugin needs in order to function for end users.
136
+
137
+
These packages are included when the Plugin is deployed to WordPress.org
138
+
139
+
Typically, packages listed in this section would be libraries that the Plugin uses.
140
+
141
+
### "require-dev"
142
+
143
+
Packages listed in the "require-dev" directive are packages that the Plugin **does not** need in order to function for end users.
144
+
145
+
These packages are **not** included when the Plugin is deployed to wordpress.org
146
+
147
+
Typically, packages listed in this section would be internal development tools for testing, such as:
148
+
- Coding Standards
149
+
- PHPStan
150
+
- PHPUnit
151
+
152
+
## Committing Work
153
+
154
+
Remember to commit your changes to your branch relatively frequently, with a meaningful, short summary that explains what the change(s) do.
155
+
This helps anyone looking at the commit history in the future to find what they might be looking for.
156
+
157
+
If it's a particularly large commit, be sure to include more information in the commit description.
158
+
159
+
## Next Steps
160
+
161
+
Once you've finished your feature or issue, you must write/amend tests for it. Refer to the [Testing Guide](#testing-guide) for a detailed walkthrough
162
+
on how to write a test.
163
+
164
+
165
+
166
+
# Testing Guide
167
+
168
+
This document describes how to:
169
+
- create and run tests for your development work,
170
+
- ensure code meets PHP and WordPress Coding Standards, for best practices and security,
171
+
- ensure code passes static analysis, to catch potential errors that tests might miss
172
+
173
+
If you're new to creating and running tests, this guide will walk you through how to do this.
174
+
175
+
For those more experienced with creating and running tests, our tests are written in TS for [Playwright](https://playwright.dev/) used for End-to-End testing,
176
+
and in PHP for [PHPUnit](https://phpunit.de/).
177
+
178
+
A PHPUnit guide for WordPress can be found [here](https://make.wordpress.org/core/handbook/testing/automated-testing/phpunit/).
179
+
180
+
## Prerequisites
181
+
182
+
If you haven't yet set up your local development environment with this Plugin repository installed, refer to the [Setup Guide](#setup-guide).
183
+
184
+
If you haven't yet created a branch and made any code changes to the Plugin or Theme, refer to the [Development Guide](#development-guide)
185
+
186
+
## Write (or modify) a test
187
+
188
+
If your work creates new functionality, write a test.
189
+
190
+
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.
191
+
192
+
Tests are written in TS using [Playwright](https://playwright.dev/) and PHP using [PHPUnit](https://phpunit.de/).
193
+
194
+
## Types of Test
195
+
196
+
There are different types of tests that can be written:
197
+
- Acceptance Tests: Test as a non-technical user in the web browser.
198
+
- Functional Tests: Test the framework (WordPress).
199
+
- Integration Tests: Test code modules in the context of a WordPress website.
200
+
- Unit Tests: Test single PHP classes or functions in isolation.
201
+
- WordPress Unit Tests: Test single PHP classes or functions in isolation, with WordPress functions and classes loaded.
202
+
203
+
There is no definitive / hard guide, as a test can typically overlap into different types (such as Acceptance and Functional).
204
+
205
+
The most important thing is that you have a test for *something*. If in doubt, an Acceptance Test will suffice.
206
+
207
+
### Writing an Acceptance Test
208
+
209
+
An acceptance test is a test that simulates a user interacting with the Plugin or Theme in a web browser.
210
+
Refer to Writing an End-to-End Test below.
211
+
212
+
### Writing an End-to-End Test
213
+
214
+
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.
215
+
216
+
E.g. for `e2e-tests/specs/checkout.spec.test.js`, the test file should be `checkout.spec.test.js`.
217
+
218
+
For more information on writing End-to-End tests, refer to the [Playwright documentation](https://playwright.dev/docs/test-intro).
219
+
220
+
You can check End-to-End [README](./e2e-tests/README.md) for more details.
221
+
222
+
## Writing a WordPress Unit Test
223
+
224
+
WordPress Unit tests provide testing of Plugin/Theme specific functions and/or classes, typically to assert that they perform as expected
225
+
by a developer. This is primarily useful for testing our API class, and confirming that any Plugin registered filters return
226
+
the correct data.
227
+
228
+
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`.
229
+
The filename should be in `lower-case-with-dash`, and the class name should be in `CamelCase`.
230
+
231
+
E.g. for `tests/php/unit/class-api-test.php`, the test class should be `class APITest extends \PHPUnit\Framework\TestCase`.
0 commit comments