Skip to content

Commit 1f68e66

Browse files
eliot-akiraeliot-akira
committed
Guide: Plugin upgrade to new setup
1 parent 195ff01 commit 1f68e66

4 files changed

Lines changed: 368 additions & 6 deletions

File tree

‎docs/pages/guides/plugin-upgrade.md‎

Lines changed: 352 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,352 @@
1+
# Plugin upgrade to new setup
2+
3+
**Prerequisites**: [Git](https://git-scm.com/), [Node](https://nodejs.org/), [Docker](https://docs.docker.com/engine/), [Bash](https://en.wikipedia.org/wiki/Bash_(Unix_shell))-compatible shell - See [Setup](/setup)
4+
5+
Here are the steps to upgrade an existing plugin with the common setup used by all new plugins.
6+
7+
- Create GitHub repository
8+
- Basic setup: Copy common files from example plugin
9+
- Local development site
10+
- Unit tests with PHPUnit
11+
- End-to-end tests with Playwright
12+
- Upgrade Framework
13+
- Upgrade Build Pipeline
14+
- Upgrade Assets Bundler
15+
- Code formatter using Roller (CSS, Sass, JavaScript, TypeScript) and [PHP Beautify](https://github.com/TangibleInc/php-beautify)
16+
17+
## Git repository
18+
19+
Create an empty repository from here: https://github.com/new
20+
21+
It can be public or private; however, at the moment the automated release pipeline for private repos is still in development.
22+
23+
Go into the local repository of the existing plugin. If you don't have it, clone it from its original location.
24+
25+
```sh
26+
git clone git@bitbucket.org:tangibleinc/example-plugin # if needed
27+
cd example-plugin
28+
```
29+
30+
List existing remote targets.
31+
32+
```sh
33+
git remote -v
34+
```
35+
36+
Replace remote `origin` with a new one pointing to GitHub. Optionally add remote `bitbucket` if you want to keep deploying to the old location until the upgrade is complete.
37+
38+
```sh
39+
git remote remove origin
40+
git remote add origin git@github.com:tangibleinc/example-plugin.git
41+
git remote add bitbucket git@bitbucket.org:tangibleinc/example-plugin
42+
```
43+
44+
Rename main branch from "master" to "main".
45+
46+
```sh
47+
git branch -M main
48+
```
49+
50+
Push to remote `origin`, setting it as the upstream of main branch.
51+
52+
```sh
53+
git push -u origin main
54+
```
55+
56+
Create and switch to a new branch for doing the upgrade work.
57+
58+
```sh
59+
git checkout -b feature/upgrade-setup
60+
```
61+
62+
This can be turned into a pull request for an optional review session before merging to the main branch.
63+
64+
## Common setup
65+
66+
To get an idea of the complete setup, see:
67+
68+
- [Example Plugin](https://github.com/TangibleInc/example-plugin)
69+
- [Folder structure and files](/wordpress/plugin/file-structure)
70+
- [Commands used during plugin development](/wordpress/plugin/develop)
71+
72+
It's recommended, but not required, to use the [Create](/modules/create/) tool to generate a new plugin that includes the complete setup.
73+
74+
```sh
75+
npm create tangible@latest
76+
```
77+
78+
This can be used as a reference for how everything works together. The tool prompts for the plugin name, title, description; then creates common setup files with those values.
79+
80+
If you want to use it as the new project folder, rename the old plugin to something else before creating the new plugin with the original name. For example:
81+
82+
```sh
83+
mv example-plugin example-plugin-old
84+
```
85+
86+
Then you can copy over the main files from the old plugin, including the `.git` folder, to the new plugin.
87+
88+
Alternatively, to manually update an existing plugin, copy and merge the following folders and files into the project.
89+
90+
- `.editorconfig`
91+
- `.github` - See [Build Pipeline](#build-pipeline)
92+
- `.gitignore`
93+
- `.prettierrc`
94+
- `.wp-env.json`
95+
- `blueprint.dev.json`
96+
- `composer.json`
97+
- `package.json`
98+
- `phpunit.xml`
99+
- `playwright.config.js`
100+
- `playwright.setup.js`
101+
- `readme.md`
102+
- `tangible.config.js` - See [Assets Bundler](#assets-bundler)
103+
- `tests`
104+
105+
If copying from the example plugin, update the file contents as needed. Examples of placeholder values: `example-plugin` (name), `Example Plugin` (title), `EXAMPLE_PLUGIN` (constant).
106+
107+
## Vendor dependencies
108+
109+
In the new setup, Composer is only used for dev dependencies needed for testing.
110+
111+
```json
112+
{
113+
"require-dev": {
114+
"phpunit/phpunit": "9.6.x-dev",
115+
"yoast/phpunit-polyfills": "2.x-dev"
116+
},
117+
"minimum-stability": "dev"
118+
}
119+
```
120+
121+
Define other vendor dependencies in `tangible.config.js` to be installed and updated by Roller. Example:
122+
123+
```js
124+
{
125+
install: [
126+
{
127+
git: 'git@github.com:tangibleinc/framework',
128+
dest: 'vendor/tangible/framework',
129+
branch: 'main',
130+
},
131+
{
132+
git: 'git@github.com:tangibleinc/updater',
133+
branch: 'main',
134+
dest: 'vendor/tangible/updater'
135+
},
136+
]
137+
}
138+
```
139+
140+
These are managed by Roller.
141+
142+
To install dependencies, run `npm install` which runs the `postinstall` script that calls `roll install`. Or run directly as `npx roll install`, after NPM packages are installed.
143+
144+
To update dependencies, run `npm run update` which calls `roll update`. Or run directly as `npx roll update`.
145+
146+
### Third-party plugins
147+
148+
For dev dependencies, add the option `--dev`. These typically include optionally supported plugins. Here's an example from [Blocks Pro](/plugins/blocks-pro).
149+
150+
```js
151+
{
152+
installDev: [
153+
// Third-party plugins
154+
{
155+
zip: 'https://downloads.wordpress.org/plugin/advanced-custom-fields.latest-stable.zip',
156+
dest: 'vendor/tangible-dev/advanced-custom-fields',
157+
},
158+
{
159+
zip: 'https://downloads.wordpress.org/plugin/beaver-builder-lite-version.latest-stable.zip',
160+
dest: 'vendor/tangible-dev/beaver-builder-lite-version',
161+
},
162+
{
163+
zip: 'https://downloads.wordpress.org/plugin/elementor.latest-stable.zip',
164+
dest: 'vendor/tangible-dev/elementor',
165+
},
166+
{
167+
zip: 'https://downloads.wordpress.org/plugin/easy-digital-downloads.latest-stable.zip',
168+
dest: 'vendor/tangible-dev/easy-digital-downloads',
169+
},
170+
{
171+
zip: 'https://downloads.wordpress.org/plugin/the-events-calendar.latest-stable.zip',
172+
dest: 'vendor/tangible-dev/the-events-calendar',
173+
},
174+
{
175+
zip: 'https://downloads.wordpress.org/plugin/lifterlms.latest-stable.zip',
176+
dest: 'vendor/tangible-dev/lifterlms',
177+
},
178+
{
179+
zip: 'https://downloads.wordpress.org/plugin/woocommerce.latest-stable.zip',
180+
dest: 'vendor/tangible-dev/woocommerce',
181+
},
182+
183+
// LearnDash
184+
{
185+
zip: 'https://static.tangible.one/vendor/sfwd-lms.zip',
186+
dest: 'vendor/tangible-dev/sfwd-lms'
187+
},
188+
{
189+
zip: 'https://static.tangible.one/vendor/learndash-course-grid.zip',
190+
dest: 'vendor/tangible-dev/learndash-course-grid'
191+
},
192+
{
193+
zip: 'https://static.tangible.one/vendor/learndash-hub.zip',
194+
dest: 'vendor/tangible-dev/learndash-hub'
195+
},
196+
],
197+
}
198+
```
199+
200+
Run `npm run install:dev` or `npm run update:dev` to update them. Or directly with `npx roll install --dev` and `npx roll update --dev`.
201+
202+
Note how they're installed in `vendor/tangible-dev`, which is excluded from the zip release package.
203+
204+
Dev dependencies are typically mounted into the Docker container in `.wp-env.json`. For example:
205+
206+
```json
207+
{
208+
"core": "WordPress/WordPress",
209+
"phpVersion": "8.2",
210+
"plugins": ["."],
211+
"mappings": {
212+
"wp-content/tangible": "./vendor/tangible",
213+
"wp-content/plugins/beaver-builder-lite-version": "./vendor/tangible-dev/beaver-builder-lite-version",
214+
"wp-content/plugins/tangible-e2e-plugin": "./vendor/tangible/framework/env/e2e-plugin",
215+
"wp-content/themes/empty-block-theme": "./vendor/tangible/framework/empty-block-theme"
216+
}
217+
}
218+
```
219+
220+
## Dev site
221+
222+
Install NPM dependencies.
223+
224+
```sh
225+
npm install
226+
```
227+
228+
Install dev dependencies like third-party plugins.
229+
230+
```sh
231+
npm run install:dev
232+
```
233+
234+
### wp-now
235+
236+
Start a quick dev site using [`wp-now`](https://github.com/WordPress/playground-tools/blob/trunk/packages/wp-now/README.md).
237+
238+
```sh
239+
npm run now
240+
```
241+
242+
The default user is `admin` with `password`. Press CTRL + C to stop.
243+
244+
This environment is meant as a temporary playground. It uses PHP-WASM which is more convenient and faster to start than Docker, but it's a bit experimental and may not be fully compatible with a normal PHP install.
245+
246+
### wp-env
247+
248+
Start a proper dev site using [`wp-env`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env).
249+
250+
```sh
251+
npm run start
252+
```
253+
254+
This starts the Docker containers for a dev site, test site, and WP-CLI. The test site's database is erased every time the unit tests are run.
255+
256+
Visit the dev site at: http://localhost:8888
257+
258+
The default PHP version is 8.2. If you need to downgrade to 7.4, for example to support a third-party plugin, update the property `phpVersion` in `.wp-env.json`; then run `npm run start:update`.
259+
260+
To stop the server.
261+
262+
```sh
263+
npm run stop
264+
```
265+
266+
To run arbitrary commands for the dev site, use `npx wp-env`.
267+
268+
```sh
269+
npx wp-env run cli cat wp-content/debug.log # See debug log
270+
npx wp-env run cli bash # Start shell session
271+
npx wp-env run cli wp # WP-CLI commands
272+
```
273+
274+
## Unit tests
275+
276+
After the dev site is started, install Composer. This needs to be done only once.
277+
278+
```sh
279+
npm run composer:install
280+
```
281+
282+
Run tests.
283+
284+
```sh
285+
npm run test
286+
```
287+
288+
## End-to-end tests
289+
290+
Install the Chromium browser engine for Playwright. This needs to be done only once.
291+
292+
```sh
293+
npm run e2e:install
294+
```
295+
296+
Run E2E tests.
297+
298+
```sh
299+
npm run e2e
300+
```
301+
302+
## Framework
303+
304+
Read the documentation for the [Framework](/modules/framework) and its [Plugin module](/modules/framework/plugin). For more context about the upgrade, see [this GitHub issue](https://github.com/TangibleInc/framework/issues/11).
305+
306+
Here are the main points of upgrading from Framework [v2](https://bitbucket.org/tangibleinc/tangible-plugin-framework) to [v3](https://github.com/TangibleInc/framework/).
307+
308+
Replace all occurences of `tgbl`, `tangible_plugin_framework`, and `$framework`.
309+
310+
Search for a keyword in the codebase.
311+
312+
```sh
313+
grep -R framework
314+
```
315+
316+
Example of old framework usage.
317+
318+
```php
319+
$framework = tangible_plugin_framework();
320+
321+
$framework->example_method();
322+
```
323+
324+
Example of new framework usage.
325+
326+
```php
327+
use tangible\framework;
328+
329+
framework\example_method();
330+
```
331+
332+
Update the way the plugin and its settings page, features, and dependencies are defined, according to the [Plugin module](/modules/framework/plugin).
333+
334+
## Build pipeline
335+
336+
Read the documentation for the [Build Pipeline](/modules/pipeline) using [GitHub Actions](https://docs.github.com/en/actions).
337+
338+
Copy the folder `.github` from the [Example Plugin](https://github.com/TangibleInc/example-plugin). The workflow files are the same for all plugins, so they don't need to be updated.
339+
340+
For reference, here's the old pipeline [v1](https://bitbucket.org/tangibleinc/tangible-pipeline) and [v2](https://bitbucket.org/tangibleinc/tangible-pipeline-v2/) using Bitbucket.
341+
342+
## Assets bundler
343+
344+
Read the documentation for [Roller](/modules/roller).
345+
346+
The section [Comparison with Tangible Builder](/modules/roller/#comparison-with-tangible-builder) explains a few small differences in the schema for the configuration file `tangible.config.js`. Update as needed.
347+
348+
## Formatter
349+
350+
Read the documentation for Roller's [Format command](/modules/roller/#format).
351+
352+
In the build configuration file `tangible.config.js`, the `format` property defines file patterns to be formatted. Update to match the existing folder structure.

‎docs/pages/setup.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,17 @@
55
Here is an example of a local development setup.
66

77
- Laptop with at least 16GB memory
8-
- Operating system: Linux, macOS, or Windows Subsystem for Linux (WSL)
9-
- Browser: [Firefox](https://www.mozilla.org/en-US/firefox/new/), Safari, or Chrome/Chromium
10-
- Editor: [Visual Studio Code](https://code.visualstudio.com/), Vim, or Emacs
8+
- Operating system: GNU/Linux, macOS, Windows Subsystem for Linux (WSL)
9+
- Browser: [Firefox](https://www.mozilla.org/en-US/firefox/new/), Chromium, Safari
10+
- Editor: [Visual Studio Code](https://code.visualstudio.com/), Vim, Emacs
1111
- Git GUI: [Source Git](https://sourcegit-scm.github.io/)
1212

1313
## Prepare
1414

1515
The following software is required for the projects in the documentation.
1616

17-
- [Node](https://nodejs.org) - JavaScript runtime (version 20 and above)
1817
- [Git](https://git-scm.com/) - Version control system
18+
- [Node](https://nodejs.org) - JavaScript runtime (version 20 and above)
1919

2020
Optionally, some projects or tasks may depend on:
2121

‎docs/sidebars.ts‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -143,13 +143,17 @@ const sidebars: SidebarsConfig = {
143143
items: [
144144
{
145145
type: 'doc',
146-
id: 'guides/types-of-documentation',
147-
label: 'Types of documentation',
146+
id: 'guides/plugin-upgrade',
148147
},
149148
{
150149
type: 'doc',
151150
id: 'guides/github-pages',
152151
},
152+
{
153+
type: 'doc',
154+
id: 'guides/types-of-documentation',
155+
label: 'Types of documentation',
156+
},
153157
],
154158
},
155159

0 commit comments

Comments
 (0)