Contributing

Coding standards

All PHP, JavaScript, CSS and HTML code must follow WordPress Coding Standards.

Requirements

It's out of scope for us to tell you exactly how to set up your local development environment, but here are some minimum requirements:

• PHP 5.6 or greater
• A web server like Apache or nginx
• MySQL 5.0 or greater
• WordPress 4.0 or greater

Our ideal recommendations for maximum performance are:

• PHP 7.4
• nginx
• MySQL 5.7 or greater
• The latest version of WordPress

We use Vagrant on this project. Consider VVV, an open source option that is used by many in the WordPress community.

Unit tests

All pull requests must have accompanying unit tests if they do not already exist. Any new features will not be considered for merging unless they have unit tests. All tests should be added in the tests directory, which follows the same directory structure as the main plugin.

You'll need PHPUnit version 6.5 to run tests for PHP 7 (version 5.7 to test PHP 5.6) and Composer to complete the installation. Initially, you'll need to set up the test environment, you can do so by running this command from the main plugin directory:

bin/install-wp-tests.sh <db-name> <db-user> <db-pass> [db-host] [wp-version]

To install dependencies that are required by the unit tests, simply run this command from the main plugin directory:

composer install

After completing the above steps, to run tests, execute the command phpunit from the main plugin directory.

Release schedule

We try to release new versions of the plugin regularly. Any issues scheduled for resolution in a specific plugin version are noted using milestones. If you make a contribution, it will go live with the next version of the plugin once approved.

When a new version is in the works, there will be an accompanying feature branch for that version. Pull requests that are to go out with a specific version of the plugin should be created against the feature branch for that version, and will be merged into that feature branch prior to release. The feature branch will be merged to the head branch when the release is ready to go out.

Release procedure

• Ensure that the feature branch (e.g., feature/v2.1.1) contains all features ready for release.
• Issue a final PR to the feature branch that bumps the version number in readme.txt (stable tag), apple-news.php (in the comment at the top of the file) and includes/class-apple-news.php (public static $version), adds a changelog entry for the release to readme.txt, and bumps the "tested up to" value in readme.txt to the latest version of WordPress.
• Merge the feature branch to the head branch.
• Create a new release for the version. The release should use version 2.1.0 as a model. The release should be titled vX.Y.Z, following semantic versioning (e.g., v2.1.1). Include the changelog in the release comments. Create a new tag for the release and ensure the tag is also named vX.Y.Z (e.g., v2.1.1). The tag should point at the head branch, which contains all of the changes that were just merged from the feature branch.
• By creating the release and the tag, a GitHub Actions workflow is automatically triggered that runs the build via DeployBot.
• The DeployBot build step will push the built version as a tag, which will automatically trigger the next GitHub action, which creates the release based on the tag.
• Check out the tagged, built release version locally and test to ensure that the plugin works as expected.
• If all is well, edit the automatically created release and uncheck the "Prerelease" option.
• Log in to DeployBot and manually trigger the Publish to WordPress.org step.
• Once deployment to WordPress.org is complete and successful, load the latest version of the plugin in a local environment from the plugin repository and test to make sure all is working as expected.
• Copy over the changelog for the new version to the Changelog page on the wiki.
• Celebrate!