Skip to content

Latest commit

 

History

History
209 lines (126 loc) · 8.67 KB

CONTRIBUTING.md

File metadata and controls

209 lines (126 loc) · 8.67 KB
Raw

Contributing to the Parse.ly plugin

Thank you for your interest in contributing to the Parse.ly plugin! We hope this document helps you get set up with everything you need to contribute, and we look forward to working with you!

Reporting issues

Please search our issues to see if your issue has been reported already and if so, comment on that issue instead of opening a new one. Please do not post private or sensitive information as the repository is public!

When creating a new issue, please add specific steps to reproduce the problem, upload any relevant screenshots, and describe what happened and what you expected would happen instead.

Contributing code

You are welcome to contribute to the plugin by submitting PRs that fix issues or introduce new features to the Parse.ly plugin.

Important branches

Ongoing development is being done against the develop branch. Release merges are performed against the trunk branch. More information about releases can be found in RELEASING.md.

To contribute code to this project, fork the repo and open a PR against the develop branch. Alternatively, if you have direct access to our repo, create a feature branch and then open an intra-repo PR from that branch against develop.

Coding standards

The Parse.ly plugin uses the PHP_CodeSniffer tool that is installed through composer. A custom ruleset is used.

The code implements strong types, so be sure to declare strict_types=1 on new PHP files, and include type definitions for parameters and return types that are compatible with the minimum version of PHP that this plugin supports.

For JavaScript, we recommend installing ESLint. This plugin includes a .eslintrc file that defines our coding standards.

Regarding inline documentation, we do our best to adhere to the WordPress Inline Documentation Standards.

Code editor

You can use any code editor or IDE to work on the plugin. For VSCode users, we use its Multi-root Workspaces feature which sets up VSCode with some recommended extensions, settings, launch configurations etc. To open the project using the workspace, follow these steps:

  1. Open the project in VSCode.
  2. Navigate to .vscode/wp-parsely.code-workspace
  3. Click on Open Workspace button that appears on the bottom right corner of VSCode UI. It should open the project in a new workspace window.

Setting up a local development environment

This plugin uses wp-env (an official WordPress package) for local development and testing, that spins up a Docker-based WordPress environment for plugin development.

Important Note: If you want to develop for WordPress VIP sites, we recommend using WordPress VIP dev-env instead.

Minimum requirements

This section lists the minimum requirements for setting up a local development environment. However, it is recommended to use updated versions of these tools for the best possible development experience. If anything doesn't seem to work, please let us know.

Docker

Docker installation depends on your OS. Please follow their official instructions. Please always use the latest possible version.

Node.js 16 (LTS)

Node.js is used in the build process of the Parse.ly plugin. If it's not already installed on your system, you can visit the Node.js website and install the latest Long Term Support (LTS) version. If you use nvm to manage node versions, you can run:

nvm install
nvm use
npm 7

Node 16 ships with npm version 7, so you don't need to update it manually. In case you don't have the latest version, you can run:

npm i -g npm

This is important to maintain the integrity of the package-lock.json file (we use lockfileVersion 2).

PHP 7.4

There are multiple ways to install PHP on your operating system. You can check out the official installation instructions from the PHP project's website.

Composer 1

The Parse.ly plugin includes several packages that require Composer, the PHP package manager. You can view the composer.json file for a full list of packages. You can install Composer through Homebrew on macOS: brew install composer. If you don't have access to Homebrew you can view instructions for how to install Composer on the Composer website.

WordPress 5.2

You don't need to install WordPress if you use the provided, Docker-based wp-env.

MySQL 5.7

To run integration tests, you will need a local MySQL installation. If you're using brew, this can be done with brew install mysql. Alternatively, you can visit the official Installing and Upgrading MySQL documentation.

Installing dependencies

Once Node.js, PHP, and Composer are installed, you will need to install dependencies in the main plugin directory:

# Install PHP dependencies.
composer install

# Use the correct Node version.
nvm use

# Install JS dependencies.
npm install

Developing locally

Starting and stopping the wp-env environment

While Docker is running, you have the following commands available:

# Start the environment.
npm run dev:start

# Stop the environment.
npm run dev:stop

npm run dev:start will start up an environment in localhost:8888, running in the background. If you have any issue running the above commands, we recommend checking that you are running an up-to-date version of Docker on your system and that you don't have any other services running on ports 8888 and 8889.

The credentials for entering wp-admin are admin and password.

Making commits

We're leveraging husky to automate some code quality commands before commits are applied. You can browse the configured hooks in this directory. For example, the coding standards and lint rules are applied prior to commit. If violations are encountered, the commit is rejected. Please note that this quality assurance process introduces a delay before every commit.

If you're on Windows, you might get an error when trying to make commits. In this case refer to WINDOWS.md.

Modifying and rebuilding plugin assets

JavaScript files that are included in the released plugin are built with the wp-scripts tool.

By default, the plugin will use the production-built JavaScript and CSS assets in the build/ folder. This is fine if you don't plan on modifying those files, but if you do, you can start a server that will compile your changes on the fly. Once your changes are complete, we ask you to rebuild the production-ready (compressed) ones. Here's the process of modifying and rebuilding the assets:

  1. Install the dependencies:

    npm i

  2. Start the build tool:

    npm run start

  3. Make and test your changes (assets are rebuilt automatically)

  4. When you have completed your changes, stop the start script and build the production assets:

    npm run build

When submitting a PR which contains asset modifications, please make sure that it includes any applicable changes to:

  • Source files (in the src directory)
  • Build tooling (including an updated package-lock.json if you've altered dependencies)
  • Built files (in the build directory)

Linting

To lint PHP code:

composer lint

To check PHP code with our coding standards:

composer cs

To auto-fix PHP code based on our coding standards:

composer cbf

To perform static analysis on PHP code using PHPStan:

composer static-analysis

To lint JS code:

npm run lint:js

# Fix auto-fixable issues.
npm run lint:js -- --fix

To lint package.json:

npm run lint:pkg-json

To lint CSS code:

npm run lint:css

# Fix auto-fixable issues.
npm run lint:css -- --fix

Testing

For testing instructions, please consult TESTING.md.