paulgibbs / coil-wordpress-plugin

Coil's Wordpress Web Monetization Plugin

Coil Web Monetization

This is the source code repository for the Coil WordPress plugin. Coil Web Monetization allows you to monetize content for all readers, Coil members only, or if you are using modern WordPress, at the block level.

---

• ZenHub Coil Wordpress Plugin Workspace Workflow
• Local Development Environment
• Development Process
• Deployment

---

ZenHub Coil Wordpress Plugin Workspace Workflow

Coil uses ZenHub to manage our Wordpress Plugin workflow. To use please install the ZenHub extension and then login to it with GitHub OAuth. Then click request access so we can approve your license.

After that you will be taken to the workspaces board where you should search for the "Wordpress Plugin" workspace.

On the "Wordpress Plugin" workspace issues move from left to right on the board.

Intake Pipelines (New Issues|New Bugs) -> Queue -> Up Next -> In Progress -> Closed

All new issues go into one of the following Intake pipelines:

New Issues	Triage (Bugs)
Any issue which is not a bug or a feature	New Bugs reported. Label: "Type: Bug"

The team reviews these issues. If they are valid bugs, a new feature we want to implement, or an issue we wish to work on we move it into the Queue.

The Queue is a prioritized list of issues the team plans to work on.

From the Queue issues are pulled into the Up Next pipeline by the Coil Team. Anyone works on these issues and they then move through the In Progress and then to the Closed pipeline once work is completed.

NOTE Issues with the label "Pragmatic" are planned to be worked on by the Pragmatic Team.

Local Development Environment

It's recommended that you use Local by Flywheel for your local development environment.

The nature of this project (a plugin) means that it is environment-agnostic, so if you prefer to install and administer WordPress using another method, then please do so.

Setting up the Development Environment using Flywheel

Ensure you have the prerequisite software installed:

• PHP 7.1+
• Composer 1.8+, installed globally.
• Local By Flywheel 3.3.0
• Node 10.15+
• An account on Coil.com.

Install the development environment:

1. Set up a new site in Flywheel:
   • Name the new site coil.
   • Choose the latest PHP version available.
   • This project does not require a specific Web Server or MySQL version; if in doubt, choose nginx and MySQL 5.6.
2. After Flywheel has created the site, from inside the root of where you chose to create the site, clone this repository into the plugins folder (make sure to add SSH key to Github plugin repo):
   • git clone [e-mail]:coilhq/coil-wordpress-plugin.git app/public/wp-content/plugins/coil-web-monetization
3. When the machine has finished provisioning, install the development dependencies:
   • cd app/public/wp-content/plugins/coil-web-monetization && composer install && npm install
4. To configure Flywheel for PHPUnit:
   • Download the following script to the base of yourapp/ folder:
     • curl -o setup-phpunit.sh https://gist.githubusercontent.com/keesiemeijer/a888f3d9609478b310c2d952644891ba/raw/
   • In Flywheel, right-click your "Coil" site and select "Open Site SSH". This will open a new terminal, and inside it, do: bash /app/setup-phpunit.sh
   • The script wil take several minutes to install PHPUnit. Once it's done, you can close the terminal.

There is no sample database to import.

Flywheel will give you the URL of where you can access your environment, and you'll have supplied the initial user account's username and password during Flywheel set up.

Development Process

The development process follows Git Flow.

Development happens in feature branches, which are merged into develop, and then eventually merged into main for deployment to production. When making changes, a feature branch should be created that branches from develop (and the corresponding merge request on Github should use develop as the target branch).

Plugin Structure

This plugin maintains a basic file structure:

• plugin.php – The main plugin file.
• includes/ – The plugin's backend/PHP code.
• assets/ – Directory containing any static assets:
  • css/ – Compiled CSS to be served to the frontend.
  • fonts/ – Web fonts, if any.
  • images/ – Images.
  • js/ – JavaScript files.
  • scss/ – SCSS source files.
• README.md – Plugin developer readme.

Within the includes/ directory, files should be organised hierarchically based on namespaces. If a namespace only contains functions, the filename should be functions.php.

If a namespace also contains classes, group those classes together with the namespace file in a {sub-namespace}/ directory. The main functions file for this namespace would be{sub-namespace}/functions.php, while classes should be in a file prefixed with class- with a "slugified" class name.

This plugin also has some complex JavaScript frontends, so there is additional structure to better match the ecosystem tooling:

• src/ – Source JavaScript and CSS files.
• build/ – Built assets, typically generated by Webpack and Babel

Assets (CSS & JS)

Some of the tooling for this plugin came from the create-guten-block project, so we have two different ways to manage CSS and JS.

Block Assets (src/)

npm start

• Use to compile and run the block in development mode.
• Watches for any changes and reports back any errors in your code.

npm run build

• Use to build production code for your block inside the dist/ folder.
• Runs once and reports back the gzip file sizes of the produced code.

Other Assets (assets/{js,scss}/)

npx grunt watch

• Use to compile and run the assets in development mode.
• Watches for any changes and reports back any errors in your code.

npx grunt build

• Use to build production code for your assets inside the assets/{css,js} folders.

Integration Tests

New tests should be written where it makes sense. With Flywheel, the PHPUnit tests have to be run inside the Flywheel environment. To do this:

• In Flywheel, right-click your "Coil" site and select "Open Site SSH". This will open a new terminal.
• Inside it, change into the plugin folder: cd /app/public/wp-content/plugins/coil-web-monetization.
• To run all tests, simply do: phpunit.

At this moment in time, the tests are not run automatically on public CI services.

Installing plugin

• for testing, the Github repo can be zipped up and the zip used to install the Coil plugin on WordPress
  • on Github, go to thefront page and click on "Clone or download"
  • choose "Download ZIP"
• for production, use command line grunt zip to create a zip in the /resources/ folder. This removes development files such as composer.json and the tests folder.

Production Build

The zip and the tag are different builds -- the tag is obviously the source version, and the zip has some build files removed. So, to generate the versions you'll want to distribute:

1. composer install && npm install
2. npm run build && npx grunt build
3. If you want to change the version number, update it in package.json and run npx grunt version
4. (commit changes from above steps
5. npx grunt zip -- it will make a zip and put it in the releases/ folder.
6. Take that zip unzip the file and commit it to SVN that way and then get it onto WordPress.org Plugins SVN.