Skip to content

Latest commit

 

History

History
307 lines (230 loc) · 9.9 KB

DEVELOPMENT.md

File metadata and controls

307 lines (230 loc) · 9.9 KB

Contributing to the OneAccess as a Developer

Code contributions, bug reports, and feature requests are welcome! The following sections provide guidelines for contributing to this project, as well as information about development processes and testing.

Table of Contents

Directory Structure

Click to expand 
├── assets
│   └── src
│       ├── admin
│       │   ├── manage-users
│       │   │   └── index.js
│       │   ├── onboarding
│       │   │   ├── index.tsx
│       │   │   └── page.tsx
│       │   └── settings
│       │       └── index.js
│       ├── components
│       │   ├── CreateUser.js
│       │   ├── ProfileRequests.js
│       │   ├── SharedUsers.js
│       │   ├── SiteModal.js
│       │   ├── SiteSettings.js
│       │   └── SiteTable.js
│       ├── css
│       │   ├── admin-user.scss
│       │   ├── admin.scss
│       │   ├── editor.scss
│       │   ├── manage-users.scss
│       │   └── onboarding.scss
│       ├── images
│       │   ├── banner.svg
│       │   └── logo.svg
│       └── js
│           ├── admin.js
│           ├── editor.js
│           ├── main.js
│           ├── user-profile.js
│           └── utils.js
├── babel.config.js
├── composer.json
├── composer.lock
├── docs
│   ├── CODE_OF_CONDUCT.md
│   ├── CONTRIBUTING.md
│   ├── DEVELOPMENT.md
│   ├── INSTALLATION.md
│   └── SECURITY.md
├── inc
│   ├── Autoloader.php
│   ├── Contracts
│   │   ├── Interfaces
│   │   │   └── Registrable.php
│   │   └── Traits
│   │       └── Singleton.php
│   ├── Encryptor.php
│   ├── Main.php
│   └── Modules
│       ├── Core
│       │   ├── Assets.php
│       │   ├── DB.php
│       │   ├── Hooks.php
│       │   ├── Rest.php
│       │   └── User_Roles.php
│       ├── Rest
│       │   ├── Abstract_REST_Controller.php
│       │   ├── Actions_Controller.php
│       │   ├── Basic_Options_Controller.php
│       │   ├── Brand_Site_Controller.php
│       │   └── Governing_Site_Controller.php
│       ├── Settings
│       │   ├── Admin.php
│       │   └── Settings.php
│       └── User
│           ├── Notice.php
│           └── Profile_Request.php
├── languages
│   └── oneaccess.pot
├── LICENSE
├── oneaccess.php
├── package-lock.json
├── package.json
├── phpcs.xml.dist
├── phpstan.neon.dist
├── phpunit.xml.dist
├── README.md
├── readme.txt
├── tests
│   ├── _output
│   │   ├── debug.log
│   │   └── phpcs-cache.json
│   ├── bootstrap.php
│   └── phpunit
├── tsconfig.json
├── uninstall.php
├── webpack.config.js
└── wp-assets
    ├── screenshot-1.png
    ├── screenshot-2.png
    ├── screenshot-3.png
    ├── screenshot-4.png
    └── screenshot-5.png

Local setup

To set up locally, clone the repository into plugins directory of your WordPress installation:

Prerequisites

  • Node.js: v22+ (NVM recommended )
  • Docker
  • Composer: (if you prefer to run the Composer tools locally)

You can use Docker and the wp-env tool to set up a local development environment, instead of manually installing the specific testing versions of WordPress, PHP, and Composer. For more information, see the wp-env documentation.

Installation

  1. Clone the repository:

    git clone https://github.com/rtCamp/OneAccess.git

  2. Change into the project folder and install the development dependencies:

    ## If you're using NVM, make sure to use the correct Node.js version:
nvm install && nvm use

## Then install the NPM dependencies:
npm install

# And the Composer dependencies:
composer install

  3. Start the local development environment:

    npm run wp-env start

The WordPress development site will be available at http://localhost:8888 and the WP Admin Dashboard will be available at http://localhost:8888/wp-admin/. You can log in to the admin using the username admin and password password.

Useful Commands

Installing Dependencies

  • composer install: Install PHP dependencies.
  • npm install: Install JavaScript dependencies.

Accessing the Local Environment

  • npm run wp-env start: Start the local development environment.
  • npm run wp-env stop: Stop the local development environment.
  • npm run wp-env run tests-cli YOUR_CMD_HERE: Run WP-CLI commands in the local environment.

For more information on using wp-env, see the wp-env documentation.

Linting and Formatting

  • npm run lint:css: Runs stylelint on the CSS code.
  • npm run lint:js: Runs ESLint on the JavaScript code.
  • npm run lint:js:fix: Autofixes ESLint issues.
  • npm run lint:js:types: Runs TypeScript's tsc to check for type errors.
  • npm run lint:php: Runs PHPCS linting on the PHP code.
  • npm run lint:php:fix: Autofixes PHPCS linting issues.
  • npm run lint:php:stan: Runs PHPStan static analysis on the PHP code.

Running Tests

PHPUnit tests can be run using the following command:

npm run test:php

To generate a code coverage report, make sure to start the testing environment with coverage mode enabled:

npm run wp-env start -- --xdebug=coverage

npm run test:php

You should see the html coverage report in the tests/_output/html directory and the clover XML report in tests/_output/php-coverage.xml.

Building the plugin for distribution

To build the plugin for distribution, you can use the following commands`:

# IMPORTANT!: Make sure you've cleaned up any dev-dependencies from Composer first:
composer install --no-dev

# Clean install of node modules.
npm ci

# Create a production-ready build:
npm run build:prod

## Create the zip file for distribution:
npm run plugin-zip

Code Contributions (Pull Requests)

Workflow

The develop branch is used for active development, while main contains the current stable release. Always create a new branch from develop when working on a new feature or bug fix.

Branches should be prefixed with the type of change (e.g. feat, chore, tests, fix, etc.) followed by a short description of the change. For example, a branch for a new feature called "Add new feature" could be named feat/add-new-feature.

Code Quality / Code Standards

This project uses several tools to ensure code quality and standards are maintained:

PHP_CodeSniffer

This project uses PHP_CodeSniffer to enforce WordPress Coding Standards. We use the WPGraphQL Coding Standards ruleset, which is a superset of WPCS, VIPCS, and Slevomat Coding Standard tailored for the WPGraphQL ecosystem.

Our specific ruleset is defined in the phpcs.xml.dist file.

You can run the PHP_CodeSniffer checks using the following command:

npm run lint:php

PHP_CodeSniffer can automatically fix some issues. To fix issues automatically, run:

npm run lint:php:fix

PHPStan

This project uses PHPStan to perform static analysis on the PHP code. PHPStan is a PHP Static Analysis Tool that focuses on finding errors in your code without actually running it.

Our specific configuration is defined in the phpstan.neon.dist file.

You can run PHPStan using the following command:

npm run lint:php:stan

ESLint

This project uses ESLint through @wordpress/scripts and @wordpress/eslint-plugin for JavaScript linting, following WordPress coding standards and best practices.

Our specific ESLint configuration is defined in the .eslintrc.json file.

You can run ESLint on JavaScript files using:

npm run lint:js

To automatically fix JavaScript linting issues:

npm run lint:js:fix

Stylelint

This project uses Stylelint through @wordpress/scripts for CSS linting, following WordPress coding standards and best practices.

Our specific Stylelint configuration is defined in the .stylelintrc.json file.

You can run Stylelint on CSS files using:

npm run lint:css

Releasing

  1. Ensure all changes are committed and tested.
  2. Update changelogs, version numbers, and n.e.x.t tags.
  3. Push develop branch to main.
  4. Create a new GitHub release draft with the new tag.