Skip to content

Latest commit

 

History

History
260 lines (172 loc) · 9.59 KB

CONTRIBUTING.md

File metadata and controls

260 lines (172 loc) · 9.59 KB
Raw

Contributing

Thank you for thinking about contributing to Orbit Fox! All sorts of contributions are welcomed.

License

Orbit Fox is licensed under the GPLv2+, and all contributions to Orbit Fox will be released under the GPLv2+ license. By contributing to this repository, you agree to release your contribution under the GPLv2+ license.

Setting Up Local Environment

You need a WordPress Environment to run the plugin on. This project needs a lot of different packages to be installed before you can start coding, but we've made the process easier with Docker.

Getting Started with Docker

The quickest way to get up and running is to use the provided Docker setup which takes care of setting up the environment for you within seconds. Install docker and docker-compose by following the most recent instructions on the Docker site.

Once Docker is installed, fork Orbit Fox repository. Clone your fork of this project and enter the working directory:

git clone http://github.com/YOUR-USERNAME/themeisle-companion/
cd themeisle-companion

Once inside the folder, you can run the following command to start your Docker container:

docker-compose up -d

This will make your WordPress instance up and running at http://localhost:8888

  • If you want to use a different port for your environment, then you can change it from docker-compose.yml file.

  • If you're developing themes, or core WordPress functionality alongside Orbit Fox, you can make the WordPress files accessible in /themeisle-companion/wordpress/ folder in your home directory.

  • If you want bash access to your environment, you can use the following command to find the ID of your Docker container:

docker ps

And then you can get bash access with the following command:

docker exec -it <ID OF YOUR CONTAINER> bash

If you want to stop your Docker container, for the time being, you can use the following command:

docker-compose stop

Moreover, if you want to delete your Docker instance, you can use:

docker-compose down

Installing Dependencies

Once you've bash access of your WordPress container, you need to enter your Orbit Fox directory with:

cd /var/www/html/wp-content/plugins/themeisle-companion/

Now, we need to install npm and composer dependencies with the following commands:

npm install
composer install

Now you can start making your changes to the plugin.

Running Grunt Tasks

We use Grunt for automating many tasks, such as compiling Sass to CSS, PHP Code Sniffer, and more.

Once you have made your changes, you can run Grunt tasks by running:

grunt local

It will take some time to finish all the tasks. If there are any issues found in PHP or JavaScript, it gives you a detailed log inside /logs/ folder of the plugin. Fix those issues and run grunt local again until it finishes without an error.

PHP_CodeSniffer

To run PHP_CodeSniffer, run composer lint. This will run the WordPress Coding Standards checks. To fix automatically fixable issues, run composer format.

PHP Unit Testing

Tests for PHP use PHPUnit as the testing framework, which is run with:

phpunit

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.

Types of Test

There are different types of tests that can be written:

  • Acceptance Tests: Test as a non-technical user in the web browser.
  • Functional Tests: Test the framework (WordPress).
  • Integration Tests: Test code modules in the context of a WordPress website.
  • Unit Tests: Test single PHP classes or functions in isolation.
  • WordPress Unit Tests: Test single PHP classes or functions in isolation, with WordPress functions and classes loaded.

There is no definitive / hard guide, as a test can typically overlap into different types (such as Acceptance and Functional).

The most important thing is that you have a test for something. If in doubt, an Acceptance Test will suffice.

Writing an Acceptance Test

An acceptance test is a test that simulates a user interacting with the Plugin or Theme in a web browser. Refer to Writing an End-to-End Test below.

Writing an End-to-End Test

To write an End-to-End test, create a new file under e2e-tests/specs with the name of the spec or functionality you are testing, and add .spec.test to the file name.

E.g. for e2e-tests/specs/checkout.spec.test.js, the test file should be checkout.spec.test.js.

For more information on writing End-to-End tests, refer to the Playwright documentation.

You can check End-to-End README for more details.

Writing a WordPress Unit Test

WordPress Unit tests provide testing of Plugin/Theme specific functions and/or classes, typically to assert that they perform as expected by a developer. This is primarily useful for testing our API class, and confirming that any Plugin registered filters return the correct data.

To create a new WordPress Unit Test, create a new file under tests/php/unit with the name of the class you are testing, and the suffix Test. The filename should be in lower-case-with-dash, and the class name should be in CamelCase.

E.g. for tests/php/unit/class-api-test.php, the test class should be class APITest extends \PHPUnit\Framework\TestCase.

<?php
class APITest extends \PHPUnit\Framework\TestCase
{
    /**
     * @var \WpunitTester
     */
    protected $tester;
    
    public function setUp(): void
    {
        // Before...
        parent::setUp();
        // Your set up methods here.
    }
    public function tearDown(): void
    {
        // Your tear down methods here.
        // Then...
        parent::tearDown();
    }
    // Tests
    public function test_it_works()
    {
        $post = static::factory()->post->create_and_get();
        
        $this->assertInstanceOf(\WP_Post::class, $post);
    }
}

Run PHPUnit Tests

Once you have written your code and test(s), run the tests to make sure there are no errors.

./vendor/bin/phpunit tests/php/unit/class-api-test.php

Any errors should be corrected by making applicable code or test changes.

Run PHP CodeSniffer

In the Plugin's or Theme's directory, run the following command to run PHP_CodeSniffer, which will check the code meets Coding Standards as defined in the phpcs.tests.xml configuration:

composer run lint

--standard=phpcs.tests.xml tells PHP CodeSniffer to use the Coding Standards rules / configuration defined in phpcs.tests.xml. These differ slightly from WordPress' Coding Standards, to ensure that writing tests isn't a laborious task, whilst maintain consistency in test coding style. -v produces verbose output -s specifies the precise rule that failed

Any errors should be corrected by either:

  • making applicable code changes
  • running composer run format to automatically fix coding standards

Need to change the PHP or WordPress coding standard rules applied? Either:

  • ignore a rule in the affected code, by adding phpcs:ignore {rule}, where {rule} is the given rule that failed in the above output.
  • edit the phpcs.tests.xml file.

Sending a Pull Request

A good workflow for pull requests to follow is listed below:

  • Fork Orbit Fox repository
  • Clone forked repository
  • Use development branch for your changes, or create a new branch from development branch.
  • Setup environment
  • Make code changes
  • Run Grunt tasks and PHPUnit tests.
  • Push branch to forked repository
  • Submit Pull Request

Reporting Security Issues

ThemeIsle team takes security bugs very seriously. Do not report potential security vulnerabilities here. Email them privately to our team at [email protected]

Reporting a Bug

We use GitHub issues for tracking bugs. When filing an issue, make sure to answer these questions:

  • What version of Orbit Fox are you using?
  • What version of WordPress are you using are you using?
  • What did you do?
  • What did you expect to see?
  • What did you see instead?

Explain the problem and include additional details to help maintainers reproduce the problem:

  • Use a clear and descriptive title for the issue to identify the problem.
  • Describe the exact steps which reproduce the problem in as many details as possible, including screenshots if needed.

Localizing Orbit Fox Plugin

You don't need to be a developer to contribute to Orbit Fox. You can also contribute to the project by translating it to your language. You can find your locale here.

Language packs are automatically generated once 95% of the plugin's strings are translated and approved for a locale.