Skip to content

Contributing

Jump to bottom
Weston Ruter edited this page Nov 11, 2024 · 13 revisions

We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow.

Getting Started

To start, clone this repository into any WordPress install being used for development:

git clone [email protected]:GoogleChromeLabs/pwa-wp.git wp-content/plugins/pwa
cd wp-content/plugins/pwa
npm install
composer install
npm run build

For a development environment using wp-env, see https://github.com/GoogleChromeLabs/pwa-wp/pull/778

You may then just activate the plugin in the admin or via WP-CLI: wp plugin activate pwa.

Your WordPress install must be configured to serve responses over HTTPS. Without this, your browser will refuse to install the service worker. The exception here is if your WordPress install is located at localhost, in which case HTTPS is not required. But in general, WordPress development environments are often located at domains example.test or example.local, and for them:

Pull requests will be checked against WordPress-Coding-Standards with PHPCS, and for JavaScript linting is done with ESLint. The pre-commit hook will runs these tests will automatically prior to pushing.

Creating a Plugin Build

To create a build of the plugin for installing in WordPress as a ZIP package, do:

npm run build

This will create an pwa.zip in the plugin directory which you can install. The contents of this ZIP are also located in the build directory which you can rsync somewhere as well.

PHPUnit Testing

Please run these tests in an environment with WordPress unit tests installed, like VVV.

Run tests:

$ phpunit

Run tests with an HTML coverage report:

$ phpunit --coverage-html /tmp/report

When you push a commit to your PR, Travis CI will run the PHPUnit tests and sniffs against the WordPress Coding Standards.

Creating a Release

Contributors who want to make a new release, follow these steps:

  1. Bump plugin versions in pwa.php (×2: the metadata block in the header and also the PWA_VERSION constant), and the Stable tag in readme.txt. Verify via npx grunt shell:verify_matching_versions.
  2. Run npm install; docker run -it --rm --name composer-install -v "$PWD":/app -w /app php:8.0-cli-alpine sh -c "wget -O /tmp/composer.phar https://getcomposer.org/download/latest-2.x/composer.phar && php /tmp/composer.phar install"
  3. Do npm run build.
  4. Install the pwa.zip onto a normal WordPress install running a stable release build; do smoke test to ensure it works.
  5. (Optional) Draft blog post about the new release, presumably on Make/Core.
  6. Draft new release on GitHub targeting the release branch, with the new plugin version as the tag and release title. Attaching the pwa.zip build to the release. Include link to changelog in release description.
  7. Run npm run deploy to to commit the plugin to WordPress.org.
  8. Open pending release verification email. Review changes in SVN.
  9. Publish GitHub release.
  10. Confirm the release on WordPress.org.
  11. Verify the release is available on WordPress.org; try installing it on a WordPress install and confirm it works.
  12. (Optional) Publish release blog post, including link to GitHub release.
  13. Close the GitHub milestone.
  14. For major releases, create a release branch (x.y).
  15. Bump versions in pwa.php on develop branch to next …-alpha; do the same in the release branch.
  16. Make announcements.

Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.

You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.

Code reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Contributors list policy

The list of contributors who are featured on the WordPress.org plugin directory are subject to change over time. The organizations and individuals who contribute significantly and consistently (e.g. 3-month period) to the project are eligible to be listed. Those listed should generally be considered as those who take responsibility for the project (i.e. owners). Note that contributions include more than just code, though contributors who commit are most visible. The sort order of the contributors list should generally follow the sort order of the GitHub contributors page, though again, this order does not consider work in issues and the support forum, so it cannot be relied on solely.

Community Guidelines

This project follows Google's Open Source Community Guidelines.

Clone this wiki locally