Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
97 lines (57 loc) · 4.42 KB

DEVELOPMENT.md

File metadata and controls

97 lines (57 loc) · 4.42 KB

Development Guide

This document describes the high level workflow used when working on the Kit WordPress Plugin.

You're free to use your preferred IDE and Git client.

Prerequisites

If you haven't yet set up your local development environment with the Kit Plugin repository installed, refer to the Setup Guide.

Create a Branch

In your Git client / command line, create a new branch:

  • If this 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
  • If this is for a feature/bug that has a GitHub Issue number, enter issue-XXX, replacing XXX with the GitHub issue number

Once done, make sure you've switched to your new branch, and begin making the necessary code additions/changes/deletions.

Coding Standards

Code must follow WordPress Coding standards, which is checked when running tests (more on this below).

Security and Sanitization

When outputting data, escape it using WordPress' escaping functions such as esc_html(), esc_attr__(), wp_kses(), wp_kses_post().

When reading user input, sanitize it using WordPress' sanitization functions such as sanitize_text_field(), sanitize_textarea_field().

When writing to the database, prepare database queries using $wpdb->prepare()

Never trust user input. Sanitize it.

Make use of WordPress nonces for saving form submitted data.

Coding standards will catch any sanitization, escaping or database queries that aren't prepared.

Composer Packages

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.

"require"

Packages listed in the "require" directive are packages that the Plugin needs in order to function for end users.

These packages are included when the Plugin is deployed to wordpress.org

Typically, packages listed in this section would be libraries that the Plugin uses, such as:

  • Kit WordPress Libraries; a shared connection of WordPress specific API, Resource and Review Request classes that are used across multiple Kit WordPress Plugins.

"require-dev"

Packages listed in the "require-dev" directive are packages that the Plugin does not need in order to function for end users.

These packages are not included when the Plugin is deployed to wordpress.org

Typically, packages listed in this section would be internal development tools for testing, such as:

  • Coding Standards
  • PHPStan
  • Codeception

CSS

Run npm run watch:css to compile frontend CSS to resources/frontend/css/frontend.css when working on SCSS in the resources/frontend/scss folder.

JS

Run npm run watch:js to compile frontend JS to resources/frontend/js/dist/frontend-min.js when working on JS in the resources/frontend/js folder.

Build

Run npm run build to:

  • fix CSS to WordPress Coding Standards (npm run fix:css)
  • lint CSS to check WordPress Coding Standards met after any fixes (npm run lint:css)
  • fix JS to WordPress Coding Standards (npm run fix:js)
  • lint JS to check WordPress Coding Standards met after any fixes (npm run lint:js)
  • compile frontend CSS from resources/frontend/scss to resources/frontend/css/frontend.css (npm run build:css)
  • compile frontend JS from resources/frontend/js to resources/frontend/js/dist (npm run build:js)

If the build process fails, review the terminal and make applicable changes:

npm run build errors

GitHub actions will run this step for you on testing and deployment, but it's a useful command in development if you need a single command to cover CSS + JS.

Committing Work

Remember to commit your changes to your branch relatively frequently, with a meaningful, short summary that explains what the change(s) do. This helps anyone looking at the commit history in the future to find what they might be looking for.

If it's a particularly large commit, be sure to include more information in the commit's description.

Next Steps

Once you've finished your feature or issue, you must write/amend tests for it. Refer to the Testing Guide for a detailed walkthrough on how to write a test.