6.0 KiB
Contributing to Query Monitor
Code contributions, bug reports, and feedback are very welcome. These should be submitted through the GitHub repository. Development happens in the develop
branch, and any pull requests should be made against that branch please.
Reviews on WordPress.org
If you enjoy using Query Monitor I would greatly appreciate it if you left a positive review on the WordPress.org Plugin Directory. This is the fastest and easiest way to contribute to Query Monitor 😄.
Reporting Security Issues
You can report security bugs through the Patchstack Vulnerability Disclosure Program. The Patchstack team helps validate, triage, and handle any security vulnerabilities. Report a security vulnerability here.
Do not report security issues on GitHub or the WordPress.org support forums. Thank you.
Inclusivity and Code of Conduct
Contributions to Query Monitor are welcome from anyone. Whether you are new to Open Source or a seasoned veteran, all constructive contribution is welcome and I'll endeavour to support you when I can.
This project is released with a contributor code of conduct and by participating in this project you agree to abide by its terms. The code of conduct is nothing to worry about, if you are a respectful human being then all will be good.
Setting up Locally
You can clone this repo and activate it like a normal WordPress plugin, but you'll need to install the developer dependencies in order to build the assets and you'll need to have Docker Desktop installed to run the tests.
Prerequisites
To run the tests, you'll also need:
- Docker Desktop running Docker Compose version 2.20 or higher
Setup
-
Install the PHP dependencies:
composer install
-
Install the Node dependencies:
npm install
Building the Assets
To compile the Sass files into CSS:
npm run build
To start the file watcher which will watch for changes and automatically compile the Sass:
npm run watch
Running the Tests
The test suite includes acceptance tests which run in a Docker container. Ensure Docker Desktop is running before running the tests.
To run the whole test suite which includes integration tests, acceptance tests, linting, and static analysis:
composer test
To run tests individually, run one of:
composer test:phpcs
composer test:phpstan
composer test:integration
composer test:acceptance
The individual integration and acceptance tests require the Docker containers to be running. To start and stop them, use:
composer test:start
composer test:stop
Releasing a New Version
These are the steps to take to release a new version of Query Monitor (for contributors who have push access to the GitHub repo).
Prior to Release
- Check the milestone on GitHub for open issues or PRs. Fix or reassign as necessary.
- If this is a non-patch release, check issues and PRs assigned to the patch or minor milestones that will get skipped. Reassign as necessary.
- Ensure you're on the
develop
branch and all the changes for this release have been merged in. - Ensure both
README.md
andreadme.txt
contain up to date descriptions, "Tested up to" versions, FAQs, screenshots, etc.- Query Monitor supports the last nine versions of WordPress (support for versions up to approximately three years old)
- Ensure
.gitattributes
is up to date with all files that shouldn't be part of the build.- To do this, run
git archive --output=qm.zip HEAD
then check the contents for files that shouldn't be part of the package.
- To do this, run
- Run
composer test
and ensure everything passes. - Run
git push origin develop
(if necessary) and ensure CI is passing. - Prepare a changelog for the Releases page on GitHub.
For Release
- Bump the plugin version number:
npm run bump:patch
for a patch release (1.2.3 => 1.2.4)npm run bump:minor
for a minor release (1.2.3 => 1.3.0)npm run bump:major
for a major release (1.2.3 => 2.0.0)
git push origin develop:release
- Wait for the Build action to complete
- Enter the changelog into the release on GitHub and publish it.
Post Release
Publishing a release on GitHub triggers an action which deploys the release to the WordPress.org Plugin Directory. No need to touch Subversion.
New milestones are automatically created for the next major, minor, and patch releases where appropriate.
- Close the milestone.
- If this is a non-patch release, manually delete any unused patch and minor milestones on GitHub.
- Check the new version has appeared on the WordPress.org plugin page (it'll take a few minutes).
- Resolve relevant threads on the plugin's support forums.
- Consume tea and cake as necessary.
Asset Updates
Assets such as screenshots and banners are stored in the .wordpress-org
directory. These get deployed as part of the automated release process too.
In order to deploy only changes to assets, push the change to the deploy
branch and they will be deployed if they're the only changes in the branch since the last release. This allows for the "Tested up to" value to be bumped as well as assets to be updated in between releases.