Skip to content

Commit

Permalink
fix: the correct folder for blueprint.json
Browse files Browse the repository at this point in the history
  • Loading branch information
Soare-Robert-Daniel committed Mar 18, 2024
1 parent 70deeb7 commit ebd989d
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 18 deletions.
File renamed without changes.
57 changes: 39 additions & 18 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,9 +121,10 @@ For specific signs:
2. Except the number formatting will be `$#,###`.

# CONTRIBUTING GUIDELINES
+ [Setup Guide](#setup-guide)
+ [Development Guide](#development-guide)
+ [Testing Guide](#testing-guide)

- [Setup Guide](#setup-guide)
- [Development Guide](#development-guide)
- [Testing Guide](#testing-guide)

# Setup Guide

Expand All @@ -136,7 +137,8 @@ WordPress, PHP, MySQL and Git - but you're free to use your preferred software.

### LAMP/LEMP stack

Any Apache/nginx, PHP 7.x+ and MySQL 5.8+ stack running WordPress. For example, but not limited to:
Any Apache/nginx, PHP 7.x+ and MySQL 5.8+ stack running WordPress. For example, but not limited to:

- Valet (recommended)
- Local by Flywheel
- Docker
Expand Down Expand Up @@ -173,6 +175,7 @@ In the cloned repository's directory, at the command line, run `composer install
This will install the development dependencies. If you want to install just the production dependencies, run `composer install --no-dev`.

The development dependencies include:

- PHPStan
- PHPUnit
- PHP_CodeSniffer
Expand All @@ -192,14 +195,13 @@ To fix automatically fixable issues, run `composer format`.
To run PHPUnit, run `phpunit` or `./vendor/bin/phpunit` if it is not configured globally.

### E2E Tests

If the folder `e2e-tests` is present, you can run the E2E tests by following the instructions in the [E2E testing](./e2e-tests/README.md).

### Next Steps

With your development environment setup, you'll probably want to start development, which is covered bellow in the **Development Guide**.



# Development Guide

This document describes the high level workflow used when working on a WordPress Plugin or Theme.
Expand All @@ -211,6 +213,7 @@ You're free to use your preferred IDE and Git client. We recommend PHPStorm or V
If you haven't yet set up your local development environment with a WordPress Plugin repository installed, refer to the [Setup Guide](#setup-guide).

his 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 feat/issue_name or fix/issue_name, where issue_name is a descriptive name for the issue

Once done, make sure you've switched to your new branch, and begin making the necessary code additions/changes/deletions.
Expand All @@ -226,7 +229,7 @@ When [outputting data](https://developer.wordpress.org/plugins/security/securing

When reading [user input](https://developer.wordpress.org/plugins/security/securing-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()``
When writing to the database, prepare database queries using `$wpdb->prepare()`

Never trust user input. Sanitize it.

Expand All @@ -236,7 +239,7 @@ Coding standards will catch any sanitization, escaping or database queries that

## 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`.
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"

Expand All @@ -253,6 +256,7 @@ Packages listed in the "require-dev" directive are packages that the Plugin **do
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
- PHPUnit
Expand All @@ -266,14 +270,13 @@ If it's a particularly large commit, be sure to include more information in the

## Next Steps

Once you've finished your feature or issue, you must write/amend tests for it. Refer to the [Testing Guide](#testing-guide) for a detailed walkthrough
Once you've finished your feature or issue, you must write/amend tests for it. Refer to the [Testing Guide](#testing-guide) for a detailed walkthrough
on how to write a test.



# Testing Guide

This document describes how to:

- create and run tests for your development work,
- ensure code meets PHP and WordPress Coding Standards, for best practices and security,
- ensure code passes static analysis, to catch potential errors that tests might miss
Expand Down Expand Up @@ -302,6 +305,7 @@ Tests are written in TS using [Playwright](https://playwright.dev/) and PHP usin
## 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.
Expand All @@ -310,7 +314,7 @@ There are different types of tests that can be written:

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.
The most important thing is that you have a test for _something_. If in doubt, an Acceptance Test will suffice.

### Writing an Acceptance Test

Expand All @@ -330,7 +334,7 @@ You can check End-to-End [README](./e2e-tests/README.md) 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
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`.
Expand All @@ -346,7 +350,7 @@ class APITest extends \PHPUnit\Framework\TestCase
* @var \WpunitTester
*/
protected $tester;

public function setUp(): void
{
// Before...
Expand All @@ -363,7 +367,7 @@ class APITest extends \PHPUnit\Framework\TestCase
public function test_it_works()
{
$post = static::factory()->post->create_and_get();

$this->assertInstanceOf(\WP_Post::class, $post);
}
}
Expand All @@ -385,7 +389,7 @@ In the Plugin's or Theme's directory, run the following command to run PHP_CodeS
as defined in the `phpcs.tests.xml` configuration:

```bash
composer run lint
composer run lint
```

`--standard=phpcs.tests.xml` tells PHP CodeSniffer to use the Coding Standards rules / configuration defined in `phpcs.tests.xml`.
Expand All @@ -395,10 +399,12 @@ in test coding style.
`-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:
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](phpcs.tests.xml) file.

Expand All @@ -409,6 +415,21 @@ Once your test(s) are written and successfully run locally, submit your branch v
It's best to create a Pull Request in draft mode, as this will trigger all tests to run as a GitHub Action, allowing you to
double-check all tests pass.

If the PR tests fail, you can make code changes as necessary, pushing to the same branch. This will trigger the tests to run again.
If the PR tests fail, you can make code changes as necessary, pushing to the same branch. This will trigger the tests to run again.

If the PR tests pass, you can publish the PR, assigning some reviewers.

## Miscellaneous

### WordPress Store Plugin Preview

The plugin preview for the WordPress store is available via the `.wordpress-org/blueprints/blueprint.json` file. Read more about this feature in the [announcement](https://make.wordpress.org/meta/2023/12/08/plugin-previews-are-now-available-for-opt-in/).

Examples:

- https://github.com/dss-web/jobbnorge-block/blob/main/.wordpress-org/blueprints/blueprint.json
- https://github.com/WordPress/wordpress-playground/blob/c6da5d622e7e49bd151bab7b72ac17501a21fea5/packages/docs/site/docs/03-build-an-app/01-index.md
- https://github.com/TablePress/TablePress/blob/62aab50e7a9c486caaeff26dff4dc01e059ecb91/.wordpress-org/blueprints/blueprint.json
- https://github.com/johnbillion/user-switching/blob/d26e982fc1389fff24e6d6572e238066e2b056d2/.wordpress-org/blueprints/blueprint.json
- https://github.com/10up/ads-txt/blob/ef95e10f5a9973aaf4cad773e8e78aafd03af059/.wordpress-org/blueprints/blueprint.json
- https://github.com/janw-me/default-featured-image/blob/de4d226216105f3d8c573dfbf28bbba89330286e/.wordpress-org/blueprints/blueprint.json

0 comments on commit ebd989d

Please sign in to comment.